Skip to content
KelkiDevelopers

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)

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

CodeDescriptionContent
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

CodeDescriptionContent
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

FieldTypeRequiredDescription
grant_typestringyes

value: client_credentials

scopestringno

Space-separated scopes. By default, all scopes granted to the client.

TokenResponse

FieldTypeRequiredDescription
access_tokenstringyes
token_typestringyes

value: Bearer

expires_inintegeryes

Validity in seconds.

scopestringyes

OAuthError

FieldTypeRequiredDescription
errorstringyes

values: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope

error_descriptionstringno

Problem

Problem details (RFC 9457), with extension members.

FieldTypeRequiredDescription
typestring (uri)yes

Stable URI of the problem type; it leads to its documentation.

titlestringyes
statusintegeryes

min. 400 · max. 599

detailstringno
instancestring (uri-reference)no
codestringyes

Stable, machine-readable code.

values: invalid_json, invalid_parameter, payload_too_large, unsupported_media_type, invalid_credentials, expired_token, insufficient_scope, live_not_enabled, account_suspended, country_not_available, trade_not_available, not_found, invalid_state, idempotency_in_progress, idempotency_key_reused, validation_failed, consent_missing, consent_version_outdated, contact_limit_reached, duplicate_request, rate_limited, quota_exceeded, agent_paused, live_creation_paused, service_unavailable, internal_error

request_idstringyes
errorsarray of FieldErrorno

RevokeRequest

FieldTypeRequiredDescription
tokenstringyes
token_type_hintstringno

values: access_token

FieldError

FieldTypeRequiredDescription
pointerstringyes

JSON Pointer (RFC 6901) of the field at fault.

detailstringyes
allowedarray of stringno

Accepted values, when the list is closed.