# 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__<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__…` 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](https://kelki.ai/developers/en/consent/)). ## 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. ## About this page - URL : https://kelki.ai/developers/en/authentication/ - Language : en - fr : https://kelki.ai/developers/fr/authentication/ - en : https://kelki.ai/developers/en/authentication/ - x-default : https://kelki.ai/developers/ - Portal : https://kelki.ai/developers/llms.txt