API keys provide machine-to-machine authentication for the KaireonAI platform. Keys use the krn_ prefix and are hashed before storage — the raw key is only shown once at creation time.
Key scopes
Every API key carries a scopes field — a JSON array of permission strings set at creation time and never changed afterwards.
scopes value | Behaviour |
|---|
[] (empty array, the default) | Legacy full-access key — permitted on all endpoints |
Non-empty array, e.g. ["scim"] | Restricted key — only the listed scopes are permitted; calls to endpoints requiring a different scope return 403 |
Defined scopes
| Scope | Required by |
|---|
"scim" | /scim/v2/* SCIM provisioning endpoints (see SCIM v2) |
POST /api/v1/api-keys
Generate a new API key. Admin only.
Request Body
| Field | Type | Required | Description |
|---|
name | string | No | Human-readable key name (defaults to key-{timestamp}) |
expiresAt | string | No | ISO 8601 expiration date. Omit for non-expiring keys |
scopes | string[] | No | Permission scopes. Each entry 1–64 chars, max 16. Omit or pass [] for a legacy full-access key |
Example — full-access key
curl -X POST https://playground.kaireonai.com/api/v1/api-keys \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-H "X-User-Role: admin" \
-d '{
"name": "CI Pipeline Key",
"expiresAt": "2027-01-01T00:00:00Z"
}'
Example — SCIM-scoped key
curl -X POST https://playground.kaireonai.com/api/v1/api-keys \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-H "X-User-Role: admin" \
-d '{
"name": "Okta SCIM Provisioner",
"scopes": ["scim"]
}'
Response (201)
{
"id": "clx...",
"name": "CI Pipeline Key",
"key": "krn_a1b2c3d4e5f6...",
"prefix": "krn_a1b2c3d4",
"scopes": [],
"expiresAt": "2027-01-01T00:00:00.000Z",
"createdAt": "2026-03-18T12:00:00.000Z",
"warning": "Store this key securely. It will not be shown again."
}
The raw API key (key field) is only returned on creation. Store it securely — it cannot be retrieved later. Scopes are set at creation and cannot be updated; revoke and re-create the key to change them.
GET /api/v1/api-keys
List all active (non-revoked) API keys for the tenant. Returns prefixes and scopes — not the full key. Admin only.
Response
{
"data": [
{
"id": "clx...",
"name": "CI Pipeline Key",
"prefix": "krn_a1b2c3d4",
"scopes": [],
"expiresAt": "2027-01-01T00:00:00.000Z",
"lastUsedAt": "2026-03-17T09:30:00.000Z",
"createdAt": "2026-03-18T12:00:00.000Z"
}
],
"total": 1
}
DELETE /api/v1/api-keys?id=
Revoke an API key (soft delete). The key immediately stops working. Admin only.
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | The API key record ID |
Request Body (optional)
| Field | Type | Required | Description |
|---|
reason | string | No | Reason for revocation (stored for audit) |
Response
204 No Content on success. 
