Skip to content
KelkiDevelopers

Authentication

Two methods, always in the Authorization header, never in the address: an API key, or an OAuth 2.0 token obtained with your client credentials.

API keys

Authorization: Bearer kk_live_Ab12Cd34_…

OAuth 2.0 client credentials

For short-lived tokens and reduced scopes per call (RFC 6749 § 4.4):

curl -s https://kelki.ai/api/v1/oauth/token -u "$KELKI_CLIENT_ID:$KELKI_CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=catalog.read requests.write requests.read"

The response gives an opaque kat_<mode>_… token, valid for 15 minutes, to use as Authorization: Bearer. The requested scopes must have been granted to the client; without scope, the token gets all of the client's scopes. Revocation: POST /oauth/revoke (RFC 7009). Errors of these two routes follow RFC 6749 § 5.2 (error, error_description).

Scopes

ScopeAccess
catalog.readCountries, trades, services, places, consent texts, account, usage.
requests.readRead your requests and their history.
requests.writeCreate, update, cancel a draft; start the e-mail confirmation.
agentConverse with the Kelki Agent (the final consent also requires requests.write).
webhooks.manageManage your webhook endpoints.

Give each key or client the minimum it needs. The specification also describes a consent.attest scope, reserved for approved partners: it is not open at launch (e-mail confirmation only).

Rotation and revocation

From a browser

Only a read-only key (catalog.read) may be used from a web page, and only for the origins declared for your account. Every write (draft, confirmation, agent) is done from your server. The API accepts no cookie: authentication goes through the header only.

Best practices