API keys
Manage the API keys that authenticate requests to this API — list the workspace's keys, create service-account keys with a chosen role, and delete keys.
All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.
Every API key endpoint is admin only.
The API key object
| Field | Type | Description |
|---|---|---|
| id | string | Key ID. |
| name | string | Display name. |
| type | string | user (a key tied to a person) or service_account (a standalone key with its own role). |
| role | string | Key role — admin, builder, or member (nullable). Admins have full access; builders manage agents and documents; members have standard access. |
| createdAt | string | When the key was created. |
| createdBy | string | Who created the key (nullable). |
| subjectUserId | string | For user keys, the ID of the user the key authenticates as; null for service-account keys. |
| lastUsedAt | string | When the key was last used to authenticate a request (nullable). |
| updatedAt | string | When the key was last updated. |
List API keys
GET /api-keys
Returns an array of all API keys in the workspace. Key values are never included — the plaintext value is returned only once, at creation.
curl 'https://{your-deployment-host}/api/v2/api-keys' \
-H 'Authorization: Bearer YOUR_API_KEY'Create API key
POST /api-keys
Creates a service-account API key with the given role.
Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Display name. |
| type | string | No | Only service_account is accepted (the default). |
| role | string | Yes | Role for the key — admin, builder, or member. |
curl -X POST 'https://{your-deployment-host}/api/v2/api-keys' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "name": "CI pipeline", "role": "builder" }'Returns 201 Created with the API key object plus a value field containing the plaintext key.
The plaintext value is returned only in this response — it can't be
retrieved again. Store it securely.
Delete API key
DELETE /api-keys/{key_id}
Permanently deletes the API key. Returns 204 No Content.
curl -X DELETE 'https://{your-deployment-host}/api/v2/api-keys/{key_id}' \
-H 'Authorization: Bearer YOUR_API_KEY'