API keys
Every call needs Authorization: Bearer <key>. 4 calls:
- List API keys:
GET /v1/api-keys - Create an API key:
POST /v1/api-keys - Revoke an API key:
DELETE /v1/api-keys/:id - Rotate an API key:
POST /v1/api-keys/:id/rotate
List API keys
GET /v1/api-keys
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | From 1 to 100. Default 50. |
cursor | string | No | Opaque cursor from next_cursor. Up to 512 characters. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
data | object[] | |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].env | enum | One of: live, test. |
data[].expires_at | string (date-time) or null | ISO 8601 timestamp. |
data[].id | string | API key id (key_...). |
data[].ip_allowlist | string[] or null | |
data[].last_used_at | string (date-time) or null | ISO 8601 timestamp. |
data[].name | string | |
data[].prefix | string | Up to 8 characters. |
data[].revoked_at | string (date-time) or null | ISO 8601 timestamp. |
data[].scopes | enum[] | |
next_cursor | string or null | Pass as cursor to get the next page; null at the end. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Create an API key
POST /v1/api-keys
The full key is returned once, in secret. Only its hash is stored.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
env | enum | No | One of: live, test. Default "live". |
expires_at | string (date-time) | No | ISO 8601 timestamp. |
ip_allowlist | string[] | No | Up to 50 items. |
name | string | Yes | Up to 80 characters. |
scopes | enum[] | Yes | Up to 3 items. |
Response 201
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
env | enum | One of: live, test. |
expires_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | API key id (key_...). |
ip_allowlist | string[] or null | |
last_used_at | string (date-time) or null | ISO 8601 timestamp. |
name | string | |
prefix | string | Up to 8 characters. |
revoked_at | string (date-time) or null | ISO 8601 timestamp. |
scopes | enum[] | |
secret | string | Shown once. Store it securely. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Revoke an API key
DELETE /v1/api-keys/:id
Revocation is immediate and permanent. Revoking twice is a no-op.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | API key id (key_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
env | enum | One of: live, test. |
expires_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | API key id (key_...). |
ip_allowlist | string[] or null | |
last_used_at | string (date-time) or null | ISO 8601 timestamp. |
name | string | |
prefix | string | Up to 8 characters. |
revoked_at | string (date-time) or null | ISO 8601 timestamp. |
scopes | enum[] |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Rotate an API key
POST /v1/api-keys/:id/rotate
Issues a new secret (and prefix) for the same key. The old secret stops working immediately.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | API key id (key_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
env | enum | One of: live, test. |
expires_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | API key id (key_...). |
ip_allowlist | string[] or null | |
last_used_at | string (date-time) or null | ISO 8601 timestamp. |
name | string | |
prefix | string | Up to 8 characters. |
revoked_at | string (date-time) or null | ISO 8601 timestamp. |
scopes | enum[] | |
secret | string | Shown once. Store it securely. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.