Uwierzytelnianie

Każde wywołanie poza GET /v1/health i POST /v1/validate/* niesie klucz API.

Nagłówek

Wyślij Authorization: Bearer <key>. Klucze tworzy się w panelu. Pełny klucz jest pokazywany raz: przechowujemy tylko jego hash SHA-256, więc zgubionego klucza nie da się odzyskać — utwórz nowy i odwołaj stary.

Authorization: Bearer co_live_…

Trzy rodzaje kluczy

Klucze live — do produkcji. Należą do planu Engine API i zużywają jego miesięczną kwotę.
Klucze testowe — darmowe dla każdego zalogowanego konta: 1000 wywołań miesięcznie, nigdy nie rozliczanych, liczonych osobno od kluczy live. GET /v1/usage zwraca dla nich env: "test".
Publiczny klucz demo — za przyciskami „Run this example”: bez konta, tylko małe synchroniczne zadania 2D, 1D i drewno, z limitem częstotliwości. Każda odpowiedź ma X-CutOptim-Demo: true.

Jedna kwota na konto

Konto może mieć do 10 aktywnych kluczy live i wszystkie zużywają tę samą miesięczną kwotę — więcej kluczy nie daje więcej wywołań. Służą do oddzielenia środowisk i integracji. Gdy kwota się skończy, każdy klucz odpowiada 402, aż minie miesiąc albo wybierzesz większy plan.

Wymiana i odwołanie klucza

Utwórz nowy klucz, przełącz na niego integrację, a potem odwołaj stary w panelu. Odwołany klucz jest od razu odrzucany z 403 key_revoked. Odwołanie nie jest operacją rozliczeniową i nie zwraca już zużytych wywołań.

GET /v1/usage

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

Tylko do odczytu: nie zużywa wywołania i nie wysyła nagłówków limitu. ⚠️ used i limit opisują KONTO, a nie klucz, którym wywołałeś: każdy aktywny klucz konta czerpie z jednej wspólnej puli, więc tworzenie kolejnych kluczy nie tworzy dodatkowego limitu. used liczy bieżący miesiąc kalendarzowy UTC dla wszystkich, remaining to limit minus used i nigdy nie schodzi poniżej zera, periodEnd to dzień zerowania jako zwykła data YYYY-MM-DD, a keyPrefix to jawny prefiks użytego klucza.

Sam klucz nie jest zwracany przez żaden endpoint — przechowywany jest wyłącznie jego hash, więc zgubiony klucz się wymienia, a nie odzyskuje.

Pole	Typ	Opis
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.