KaireonAI supports OAuth 2.0 client credentials grant (RFC 6749 section 4.4) for machine-to-machine authentication. Create OAuth clients with specific scopes, then exchange credentials for access tokens.
POST /api/v1/oauth/clients
Create a new OAuth 2.0 client. Admin only.
Request Body
| Field | Type | Required | Description |
|---|
name | string | No | Client name (defaults to oauth-client-{timestamp}) |
scopes | string[] | No | Permitted scopes: read, write, admin (default: ["read"]) |
Example
curl -X POST https://playground.kaireonai.com/api/v1/oauth/clients \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-H "X-User-Role: admin" \
-d '{
"name": "Data Pipeline Client",
"scopes": ["read", "write"]
}'
Response (201)
{
"id": "clx...",
"name": "Data Pipeline Client",
"clientId": "kci_a1b2c3d4...",
"clientSecret": "kcs_e5f6g7h8...",
"scopes": ["read", "write"],
"createdAt": "2026-03-18T12:00:00.000Z",
"warning": "Store the client secret securely. It will not be shown again."
}
The clientSecret is only returned on creation. Store it securely.
GET /api/v1/oauth/clients
List active (non-revoked) OAuth clients for the tenant. Admin only.
Response
{
"data": [
{
"id": "clx...",
"name": "Data Pipeline Client",
"clientIdPrefix": "kci_a1b2c3d4...",
"clientId": "kci_a1b2c3d4...",
"scopes": ["read", "write"],
"createdAt": "2026-03-18T12:00:00.000Z"
}
],
"total": 1
}
DELETE /api/v1/oauth/clients?id=
Revoke an OAuth client (soft delete). Admin only.
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | OAuth client record ID |
Response
204 No Content on success.
POST /api/v1/oauth/token
Exchange client credentials for an access token. Follows the OAuth 2.0 client credentials grant. Rate limited to 20 requests/min per client.
Accepts both application/x-www-form-urlencoded and application/json request bodies.
Request Body
| Field | Type | Required | Description |
|---|
grant_type | string | Yes | Must be client_credentials |
client_id | string | Yes | OAuth client ID (kci_...) |
client_secret | string | Yes | OAuth client secret (kcs_...) |
curl -X POST https://playground.kaireonai.com/api/v1/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=kci_abc&client_secret=kcs_xyz"
Example — JSON
curl -X POST https://playground.kaireonai.com/api/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "kci_abc",
"client_secret": "kcs_xyz"
}'
Response
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
Error Responses
| Status | Error | Description |
|---|
| 400 | unsupported_grant_type | Only client_credentials is supported |
| 400 | invalid_request | Missing client_id or client_secret |
| 401 | invalid_client | Invalid or revoked client credentials |
| 429 | rate_limit_exceeded | Too many token requests |
Using the Token
Include the access token in the Authorization header for subsequent API calls:
curl https://playground.kaireonai.com/api/v1/offers \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
