Autenticazione

Ogni chiamata tranne GET /v1/health e POST /v1/validate/* porta una chiave API.

L'header

Invia Authorization: Bearer <key>. Le chiavi si creano nella dashboard. La chiave completa viene mostrata una sola volta: si conserva solo il suo hash SHA-256, quindi una chiave persa non si può recuperare — creane una nuova e revoca la vecchia.

Authorization: Bearer co_live_…

Tre tipi di chiave

Chiavi live — per la produzione. Vanno con un piano Engine API e consumano la sua quota mensile.
Chiavi di test — gratuite per ogni account con accesso: 1000 chiamate al mese, mai fatturate, contate a parte rispetto alle chiavi live. GET /v1/usage risponde env: "test" per loro.
La chiave demo pubblica — dietro i pulsanti «Run this example»: senza account, solo piccoli lavori sincroni 2D, 1D e legno, con limite di frequenza. Ogni risposta porta X-CutOptim-Demo: true.

Una quota per account

Un account può avere fino a 10 chiavi live attive, e tutte consumano la stessa quota mensile: più chiavi non danno più chiamate. Servono a separare ambienti e integrazioni. Quando la quota è esaurita, ogni chiave risponde 402 finché non cambia il mese o si sceglie un piano più grande.

Ruotare e revocare una chiave

Crea la nuova chiave, passa l'integrazione su di essa, poi revoca la vecchia nella dashboard. Una chiave revocata viene rifiutata subito con 403 key_revoked. La revoca non è un'operazione di fatturazione e non restituisce le chiamate già spese.

GET /v1/usage

{
  "plan": "studio",
  "used": 137,
  "limit": 10000,
  "remaining": 9863,
  "periodEnd": "2026-08-01",
  "keyPrefix": "co_live_ab12",
  "contractVersion": "1"
}

Sola lettura: non consuma una chiamata e non invia header di rate limit. ⚠️ used e limit descrivono l’ACCOUNT, non la chiave con cui hai chiamato: ogni chiave attiva dell’account attinge a un unico monte condiviso, quindi creare più chiavi non crea più quota. used conta il mese solare UTC in corso su tutte, remaining è limit meno used e non va mai sotto zero, periodEnd è il giorno di azzeramento come semplice data YYYY-MM-DD e keyPrefix è il prefisso non segreto della chiave usata.

La chiave stessa non viene mai restituita da alcun endpoint — se ne memorizza solo l’hash, quindi una chiave persa si sostituisce, non si recupera.

Campo	Tipo	Descrizione
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.