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_…
- Format:
kk_<test|live>_<8-character identifier>_<40-character secret>. The mode is in the key. - Kelki only keeps a fingerprint of the key (HMAC-SHA256 with salt and pepper) and its visible prefix: the key is shown only once and Kelki cannot read it back.
- A key passed as a URL parameter is refused: revoke it, it may have been logged elsewhere.
- 20 active keys at most per account.
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
| Scope | Access |
|---|---|
catalog.read | Countries, trades, services, places, consent texts, account, usage. |
requests.read | Read your requests and their history. |
requests.write | Create, update, cancel a draft; start the e-mail confirmation. |
agent | Converse with the Kelki Agent (the final consent also requires requests.write). |
webhooks.manage | Manage 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
- Rotation: a new key (or a new client secret) replaces the old one, which stays valid for 24 hours, the time to deploy.
- Revocation: immediate. OAuth tokens issued with a revoked secret are revoked with it.
- Leak: if a key is published (code repository, web page), it is revoked and you are told. Replace any exposed key at once and tell Kelki.
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
- Production keys in a secrets vault or a protected environment variable; never in source code, a mobile app, a repository or a log.
- One key per environment and per service; regular rotation.
- On
401, do not retry in a loop: beyond 20 refused keys in 10 minutes, the IP address is blocked for a while.