API Keys

API keys authenticate resource operations. Keys are scoped to an organization and have either full or read_only permission.

Endpoints

Method	Path	Description
POST	/v1/api-keys	Create an API key
GET	/v1/api-keys	List API keys
DELETE	/v1/api-keys/{key_id}	Revoke an API key

---

Create an API Key

POST /v1/api-keys

Creates a new API key for the current organization. The raw key is returned once — store it immediately.

Auth: API key (full permission, any role)

curl -X POST https://api.embedd.to/v1/api-keys \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "permission": "read_only"
  }'

Field	Required	Type	Default	Description
name	Yes	string	—	Display name for the key (1-100 chars)
permission	No	string	full	full or read_only

Response (201):

{
  "key": "sk_live_new_key_abc123...",
  "api_key": {
    "id": "key_abc123",
    "org_id": "org_abc123",
    "name": "ci-pipeline",
    "key_prefix": "sk_live_new_k",
    "permission": "read_only",
    "created_by": "usr_abc123",
    "created_at": "2026-03-13T10:00:00Z",
    "revoked_at": null
  }
}

The key field is the raw API key. The key_prefix (first 12 characters) is stored for identification.

---

List API Keys

GET /v1/api-keys

Returns API keys for the current organization. Visibility depends on role:

Role	Can See
Owner	All keys in the org
Admin	All keys in the org
Member	Only their own keys

Auth: API key (any permission, any role)

curl https://api.embedd.to/v1/api-keys \
  -H "Authorization: Bearer sk_your_api_key"

Response (200):

{
  "data": [
    {
      "id": "key_abc123",
      "org_id": "org_abc123",
      "name": "ci-pipeline",
      "key_prefix": "sk_live_new_k",
      "permission": "read_only",
      "created_by": "usr_abc123",
      "created_at": "2026-03-13T10:00:00Z",
      "revoked_at": null
    }
  ]
}

Revoked keys (where revoked_at is set) are included in the list for audit purposes.

---

Revoke an API Key

DELETE /v1/api-keys/{key_id}

Revokes an API key immediately. Revoked keys cannot be used for authentication.

Auth: API key (full permission)

Role	Can Revoke
Owner	Any key in the org
Admin	Any key in the org
Member	Only their own keys

curl -X DELETE https://api.embedd.to/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer sk_your_api_key"

Response: 204 No Content

Errors:

Status	Reason
403	Member attempting to revoke another user's key
404	Key not found