Authentification
Deux méthodes, toujours dans l'en-tête Authorization, jamais dans l'adresse : une clé API, ou un jeton OAuth 2.0 obtenu avec vos identifiants de client.
Clés API
Authorization: Bearer kk_live_Ab12Cd34_…
- Format :
kk_<test|live>_<identifiant de 8 caractères>_<secret de 40 caractères>. Le mode est dans la clé. - Kelki ne garde qu'une empreinte de la clé (HMAC-SHA256 avec sel et poivre) et son préfixe visible : la clé est montrée une seule fois, Kelki ne peut pas la relire.
- Une clé passée en paramètre d'adresse est refusée : révoquez-la, elle a pu être journalisée ailleurs.
- 20 clés actives au plus par compte.
OAuth 2.0 client credentials
Pour des jetons courts et des portées réduites par appel (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"
La réponse donne un jeton opaque kat_<mode>_…, valable 15 minutes, à utiliser en Authorization: Bearer. Les portées demandées doivent avoir été accordées au client ; sans scope, le jeton reçoit toutes les portées du client. Révocation : POST /oauth/revoke (RFC 7009). Les erreurs de ces deux routes suivent le format de RFC 6749 § 5.2 (error, error_description).
Portées
| Portée | Accès |
|---|---|
catalog.read | Pays, métiers, prestations, lieux, textes d'accord, compte, consommation. |
requests.read | Lire vos demandes et leur historique. |
requests.write | Créer, modifier, annuler un brouillon ; lancer la confirmation par e-mail. |
agent | Converser avec l'Agent Kelki (l'accord final exige aussi requests.write). |
webhooks.manage | Gérer vos adresses de webhooks. |
Donnez à chaque clé ou client le minimum utile. La spécification décrit aussi une portée consent.attest, réservée à des partenaires agréés : elle n'est pas ouverte au lancement (confirmation par e-mail seule).
Rotation et révocation
- Rotation : une nouvelle clé (ou un nouveau secret client) remplace l'ancienne, qui reste valable 24 heures, le temps de déployer.
- Révocation : immédiate. Les jetons OAuth émis avec un secret révoqué sont révoqués avec lui.
- Fuite : si une clé est publiée (dépôt de code, page web), elle est révoquée et vous êtes prévenu. Remplacez sans attendre toute clé exposée et prévenez Kelki.
Depuis un navigateur
Seule une clé en lecture seule (catalog.read) peut servir depuis une page web, et seulement pour les origines déclarées pour votre compte. Toute écriture (brouillon, confirmation, agent) se fait depuis votre serveur. L'API n'accepte aucun cookie : l'authentification passe uniquement par l'en-tête.
Bonnes pratiques
- Clés de production dans un coffre de secrets ou une variable d'environnement protégée ; jamais dans le code source, une application mobile, un dépôt ou un journal.
- Une clé par environnement et par service ; rotation régulière.
- Sur
401, ne réessayez pas en boucle : au-delà de 20 clés refusées en 10 minutes, l'adresse IP est bloquée temporairement.