Authentification
Chaque appel, sauf GET /v1/health et POST /v1/validate/*, porte une clé d'API.
L'en-tête
Envoyez Authorization: Bearer <key>. Les clés se créent dans le tableau de bord. La clé complète n'est affichée qu'une fois : seul son hash SHA-256 est stocké, une clé perdue ne peut donc pas être récupérée — créez-en une nouvelle et révoquez l'ancienne.
Authorization: Bearer co_live_…Trois sortes de clés
- Clés live — pour la production. Elles vont avec une offre Engine API et puisent dans son quota mensuel.
- Clés de test — gratuites pour tout compte connecté : 1 000 appels par mois, jamais facturés, comptés à part des clés live. GET /v1/usage répond env: "test" pour elles.
- La clé de démonstration publique — derrière les boutons « Run this example » : sans compte, seulement de petits travaux synchrones 2D, 1D et bois, avec limite de débit. Chaque réponse porte X-CutOptim-Demo: true.
Un quota par compte
Un compte détient jusqu'à 10 clés live actives, et toutes puisent dans le même quota mensuel — plus de clés n'ajoutent pas d'appels. Elles servent à séparer environnements et intégrations. Quand le quota est épuisé, chaque clé répond 402 jusqu'au changement de mois ou au choix d'une offre supérieure.
Changer et révoquer une clé
Créez la nouvelle clé, basculez votre intégration dessus, puis révoquez l'ancienne dans le tableau de bord. Une clé révoquée est refusée immédiatement avec 403 key_revoked. Révoquer n'est pas une opération de facturation et ne rend pas les appels déjà consommés.
GET /v1/usage
{
"plan": "studio",
"used": 137,
"limit": 10000,
"remaining": 9863,
"periodEnd": "2026-08-01",
"keyPrefix": "co_live_ab12",
"contractVersion": "1"
}En lecture seule : ne consomme pas d'appel et n'envoie pas d'en-têtes de limitation.
⚠️ used et limit décrivent le COMPTE, pas la clé avec laquelle vous avez appelé : chaque clé active du compte puise dans une seule enveloppe commune, créer davantage de clés ne crée donc pas davantage de quota. used compte le mois calendaire UTC en cours pour toutes, remaining vaut limit moins used et ne devient jamais négatif, periodEnd est le jour de remise à zéro sous forme de date YYYY-MM-DD, et keyPrefix est le préfixe d'affichage non secret de la clé utilisée.
La clé elle-même n'est jamais renvoyée par un endpoint — seul son hachage est stocké, une clé perdue se remplace donc, elle ne se récupère pas.
| Champ | Type | Description |
|---|---|---|
| plan | string | The tier slug frozen onto the key when it was minted. Re-pricing the product later does not rewrite a live key. |
| used | integer | Calls counted in the current UTC calendar month, across EVERY key on the account — revoked keys included, so revoking a key cannot un-spend what it spent (053) — not just the one you called with. The quota is account-wide. |
| limit | integer | The monthly cap for the ACCOUNT: the largest monthly quota frozen onto any of its ACTIVE keys (049). All active keys draw on this one allowance; creating more keys does not create more quota. Keys are for separating environments and integrations (and for revoking one without disturbing the rest). |
| remaining | integer | limit − used, never negative. |
| periodEnd | string (date) | First day of next month as YYYY-MM-DD — a DATE, not a timestamp. The counter resets at 00:00 UTC on that day. |
| keyPrefix | string | Non-secret display prefix of the calling key, so you can tell which key you queried. The key itself is never returned by any endpoint. |
| contractVersion | string | Shape version. Currently "1". |
| env | "test" | Present ("test") only for a TEST key: created in the dashboard, never billed, with its own monthly allowance separate from the live keys. Absent for a live key — a live key gets exactly the body it always got. |
| keyClass | "tenant" | Present ("tenant") only for a key CutOptim issues to its own first-party service. Absent for every key you create in the dashboard. |