Une clé par application : plafonds de dépenses, expiration et clés de gestion

Depuis le 5 octobre, chaque clé de l'API DipoleML peut porter un plafond de dépenses et une expiration, et un second type de clé, la clé de gestion, crée et encadre les clés d'API depuis votre code. Cet article explique pourquoi une clé par application est la plus sûre des habitudes, comment fonctionnent les plafonds et l'expiration, et comment créer en une requête une clé plafonnée et à durée limitée.

Pourquoi donner à chaque application sa propre clé?

Toutes les clés d'API puisent dans le même solde de crédits prépayés. Une seule clé pour tout est simple jusqu'au jour où quelque chose tourne mal : une fuite oblige à la révoquer pour toutes les applications à la fois, et rien ne vous dit quelle application a dépensé quoi. Avec une clé par application, script, tâche d'intégration continue ou coéquipier :

• un nom dit où chaque clé sert;
• un plafond limite ce que chacune peut dépenser;
• une expiration met fin à une clé que vous vouliez temporaire;
• révoquer une clé laisse les autres fonctionner;
• chaque clé indique ce qu'elle a dépensé, et quand elle a fait son dernier appel facturé.

Comment fonctionnent les plafonds et l'expiration?

Un plafond est un montant en dollars US pour toute la vie de la clé. Une fois ce montant dépensé, ses appels sont refusés avec 402 et key_limit_reached; votre solde et vos autres clés ne sont pas touchés. Une expiration est une date et une heure : passé ce moment, les appels de la clé sont refusés avec 401 et key_expired. Chaque appel fait avec une clé d'API est vérifié dans cet ordre avant de s'exécuter :

Un appel qui s'exécute est débité une fois terminé, selon les jetons qu'il a utilisés : le dernier appel avant qu'une clé atteigne son plafond peut donc le dépasser légèrement. Un appel refusé n'est pas facturé.

Où fixer un plafond et une expiration?

Dans le tableau de bord, une nouvelle clé d'API peut recevoir un nom, un plafond de dépenses et une expiration, et vous pouvez changer le plafond et l'expiration plus tard ou révoquer la clé. La clé complète n'est affichée qu'une fois, à sa création : copiez-la tout de suite dans votre coffre de secrets.

Qu'est-ce qu'une clé de gestion?

Une clé de gestion est un second type de clé. Vous la créez dans le tableau de bord, elle commence par dcode_mgmt_, et elle aussi n'est affichée qu'une fois. Elle ne fonctionne que sur les chemins de gestion des clés de l'API et n'appelle jamais de modèle, alors qu'une clé d'API, qui commence par dcode_sk_, ne peut pas gérer de clés. Une clé divulguée ne peut ainsi faire que le travail de son propre type. C'est l'outil des équipes, des pipelines d'intégration continue et des agents qui distribuent leurs propres clés. L'URL de base est https://api.dipoleml.com, et chaque appel envoie la clé de gestion en jeton Bearer :

• GET /v1/management/keys : énumère vos clés d'API, avec leur plafond et ce que chacune a dépensé.
• POST /v1/management/keys : crée une clé d'API et répond 201, avec la clé elle-même une seule fois.
• GET /v1/management/keys/:id : renvoie une clé d'API.
• PATCH /v1/management/keys/:id : change son libellé, son plafond ou son expiration.
• DELETE /v1/management/keys/:id : la révoque sur-le-champ.

Comment créer une clé avec un plafond et une expiration?

Gardez la clé de gestion dans une variable d'environnement, puis envoyez une requête avec un libellé, un plafond en dollars US et une expiration au format ISO 8601. Le plafond et l'expiration sont facultatifs : sans eux, la clé n'a pas de plafond et n'expire jamais.

curl https://api.dipoleml.com/v1/management/keys \
  -H "Authorization: Bearer $DIPOLEML_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "facturation",
    "limit": 10,
    "expires_at": "2027-01-31T23:59:59Z"
  }'

La réponse, avec le statut 201, est le nouvel objet clé. La clé elle-même est dans key, dans cette réponse seulement :

{
  "id": "ak_<key id>",
  "label": "facturation",
  "status": "active",
  "created_at": "2026-10-25T15:04:05.000Z",
  "expires_at": "2027-01-31T23:59:59.000Z",
  "limit": 10,
  "used": 0,
  "limit_remaining": 10,
  "last_used_at": null,
  "key": "dcode_sk_<the new key>"
}

Remettez la clé dcode_sk_ à l'application pour laquelle elle a été créée, qui s'en sert comme de toute autre clé d'API, avec le SDK d'OpenAI pointé vers notre URL de base. used augmente à chaque appel facturé, et limit_remaining est le plafond moins ce que la clé a dépensé.

Comment modifier ou révoquer une clé depuis le code?

Un PATCH ne change que les champs que vous envoyez et renvoie la clé. Envoyez null pour retirer le plafond ou l'expiration; ici, le plafond disparaît et l'expiration change :

curl -X PATCH https://api.dipoleml.com/v1/management/keys/$KEY_ID \
  -H "Authorization: Bearer $DIPOLEML_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": null, "expires_at": "2027-06-30T23:59:59Z"}'

Un DELETE révoque la clé sur-le-champ. Son appel suivant échoue avec 401, et elle reste dans votre liste avec le statut revoked, pour que vos dossiers restent complets :

curl -X DELETE https://api.dipoleml.com/v1/management/keys/$KEY_ID \
  -H "Authorization: Bearer $DIPOLEML_MANAGEMENT_KEY"

Comment garder les clés en sécurité?

• Gardez les clés d'API sur le serveur : dans du code serveur, un script ou l'intégration continue, jamais dans une page Web ou une application mobile.
• Gardez chaque clé dans une variable d'environnement ou un coffre de secrets, hors des fichiers sous gestion de versions.
• Une clé de gestion peut créer des clés qui dépensent vos crédits. Gardez-la dans le coffre de secrets de votre intégration continue et, si elle fuit, révoquez-la dans le tableau de bord et créez-en une autre.
• Donnez aux clés que vous confiez à des machines un petit plafond et une expiration, pour qu'une clé perdue ne vous réserve pas de surprise.

Où aller ensuite?

La référence des clés de gestion donne chaque champ, et la page Authentication explique comment envoyer une clé. Pour ce que coûtent les appels, lisez ce que coûte une tâche d'IA et la page des tarifs; pour mettre une nouvelle clé au travail, lisez la diffusion en continu dans l'API DipoleML. La page de l'API présente tout ce que l'API DipoleML prend en charge.