Autentificare

Fiecare apel, cu excepția GET /v1/health și POST /v1/validate/*, poartă o cheie API.

Antetul

Trimite Authorization: Bearer <key>. Cheile se creează în panou. Cheia completă se arată o singură dată: se păstrează doar hash-ul ei SHA-256, deci o cheie pierdută nu se poate recupera — creează una nouă și revoc-o pe cea veche.

Authorization: Bearer co_live_…

Trei tipuri de chei

Chei live — pentru producție. Vin cu un plan Engine API și consumă cota lui lunară.
Chei de test — gratuite pentru orice cont conectat: 1.000 apeluri pe lună, niciodată facturate, numărate separat de cheile live. GET /v1/usage răspunde env: "test" pentru ele.
Cheia demo publică — în spatele butoanelor „Run this example”: fără cont, doar lucrări sincrone mici 2D, 1D și lemn, cu limită de frecvență. Fiecare răspuns poartă X-CutOptim-Demo: true.

O cotă pe cont

Un cont poate avea până la 10 chei live active și toate consumă aceeași cotă lunară — mai multe chei nu adaugă apeluri. Ele separă mediile și integrările. Când cota se termină, fiecare cheie răspunde 402 până la schimbarea lunii sau alegerea unui plan mai mare.

Schimbarea și revocarea unei chei

Creează cheia nouă, mută integrarea pe ea, apoi revoc-o pe cea veche în panou. O cheie revocată este refuzată imediat cu 403 key_revoked. Revocarea nu este o operațiune de facturare și nu returnează apelurile deja consumate.

GET /v1/usage

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

Doar citire: nu consumă un apel și nu trimite anteturi de rate limit. ⚠️ used și limit descriu CONTUL, nu cheia cu care ai apelat: fiecare cheie activă a contului consumă dintr-o singură alocare comună, deci mai multe chei nu înseamnă mai multă cotă. used numără luna calendaristică UTC curentă pentru toate, remaining este limit minus used și nu coboară niciodată sub zero, periodEnd este ziua de resetare ca dată simplă YYYY-MM-DD, iar keyPrefix este prefixul public al cheii folosite.

Cheia în sine nu este returnată de niciun endpoint — se stochează doar hash-ul ei, așa că o cheie pierdută se înlocuiește, nu se recuperează.

Câmp	Tip	Descriere
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.