OAuth
OAuth 2.0 “client credentials” token (RFC 6749 § 4.4) and revocation (RFC 7009).
Base URL: https://kelki.ai/api/v1.
POST /oauth/token— Get an access token (client credentials)POST /oauth/revoke— Revoke an access token (RFC 7009)
POST /oauth/token
Get an access token (client credentials)
Exchanges client_id + client_secret (HTTP Basic, RFC 6749 § 2.3.1) for an opaque 15-minute token. The requested scopes must have been granted to the client. The mode (test / live) is the client's mode.
Authentication: OAuth client credentials (HTTP Basic).
Request body
application/x-www-form-urlencoded — TokenRequest (required)
{
"grant_type": "client_credentials",
"scope": "catalog.read requests.write requests.read"
}Responses
| Code | Description | Content |
|---|---|---|
200 | Token issued. | application/json TokenResponse |
400 | Invalid request (RFC 6749 § 5.2). | application/json OAuthError |
401 | Unknown client, invalid or revoked secret. | application/json OAuthError |
429 | Rate or quota exceeded. | application/problem+json Problem |
Response example
{
"access_token": "kat_test_EXEMPLE0000000000000000000000000000000",
"token_type": "Bearer",
"expires_in": 900,
"scope": "catalog.read requests.write requests.read"
}POST /oauth/revoke
Revoke an access token (RFC 7009)
Authentication: OAuth client credentials (HTTP Basic).
Request body
application/x-www-form-urlencoded — RevokeRequest (required)
Responses
| Code | Description | Content |
|---|---|---|
200 | Token revoked (same response if the token was already invalid, RFC 7009 § 2.2). | |
401 | Unknown client or invalid secret. | application/json OAuthError |
Schemas
TokenRequest
| Field | Type | Required | Description |
|---|---|---|---|
grant_type | string | yes | value: |
scope | string | no | Space-separated scopes. By default, all scopes granted to the client. |
TokenResponse
| Field | Type | Required | Description |
|---|---|---|---|
access_token | string | yes | |
token_type | string | yes | value: |
expires_in | integer | yes | Validity in seconds. |
scope | string | yes |
OAuthError
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | values: |
error_description | string | no |
Problem
Problem details (RFC 9457), with extension members.
| Field | Type | Required | Description |
|---|---|---|---|
type | string (uri) | yes | Stable URI of the problem type; it leads to its documentation. |
title | string | yes | |
status | integer | yes | min. 400 · max. 599 |
detail | string | no | |
instance | string (uri-reference) | no | |
code | string | yes | Stable, machine-readable code. values: |
request_id | string | yes | |
errors | array of FieldError | no |
RevokeRequest
| Field | Type | Required | Description |
|---|---|---|---|
token | string | yes | |
token_type_hint | string | no | values: |
FieldError
| Field | Type | Required | Description |
|---|---|---|---|
pointer | string | yes | JSON Pointer (RFC 6901) of the field at fault. |
detail | string | yes | |
allowed | array of string | no | Accepted values, when the list is closed. |