Authentifizierung

Jeder Aufruf außer GET /v1/health und POST /v1/validate/* trägt einen API-Schlüssel.

Der Header

Senden Sie Authorization: Bearer <key>. Schlüssel werden im Dashboard angelegt. Der vollständige Schlüssel wird einmal angezeigt: Gespeichert wird nur sein SHA-256-Hash, ein verlorener Schlüssel lässt sich also nicht wiederherstellen — legen Sie einen neuen an und widerrufen Sie den alten.

Authorization: Bearer co_live_…

Drei Arten von Schlüsseln

Live-Schlüssel — für den Produktivbetrieb. Sie gehören zu einem Engine-API-Tarif und verbrauchen dessen Monatskontingent.
Testschlüssel — kostenlos für jedes angemeldete Konto: 1.000 Aufrufe pro Monat, nie berechnet, getrennt von den Live-Schlüsseln gezählt. GET /v1/usage antwortet für sie mit env: "test".
Der öffentliche Demo-Schlüssel — hinter den „Run this example“-Schaltflächen: ohne Konto, nur kleine synchrone 2D-, 1D- und Holz-Aufträge, mit Ratenlimit. Jede Antwort trägt X-CutOptim-Demo: true.

Ein Kontingent pro Konto

Ein Konto hat bis zu 10 aktive Live-Schlüssel, und alle verbrauchen dasselbe Monatskontingent — mehr Schlüssel bedeuten kein größeres Kontingent. Sie trennen Umgebungen und Integrationen. Ist das Kontingent aufgebraucht, antwortet jeder Schlüssel mit 402, bis der Monat wechselt oder ein größerer Tarif gewählt wird.

Schlüssel wechseln und widerrufen

Legen Sie den neuen Schlüssel an, stellen Sie Ihre Integration darauf um und widerrufen Sie dann den alten im Dashboard. Ein widerrufener Schlüssel wird sofort mit 403 key_revoked abgewiesen. Widerrufen ist kein Abrechnungsvorgang und gibt bereits verbrauchte Aufrufe nicht zurück.

GET /v1/usage

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

Nur lesend: verbraucht keinen Aufruf und sendet keine Rate-Limit-Header.

⚠️ used und limit beziehen sich auf das KONTO, nicht auf den Schlüssel, mit dem Sie aufgerufen haben: jeder aktive Schlüssel des Kontos schöpft aus einem gemeinsamen Kontingent, mehr Schlüssel bedeuten also nicht mehr Kontingent. used zählt den laufenden UTC-Kalendermonat über alle hinweg, remaining ist limit minus used und wird nie negativ, periodEnd ist der Rücksetztag als reines YYYY-MM-DD-Datum, und keyPrefix ist das nicht geheime Anzeigepräfix des verwendeten Schlüssels.

Der Schlüssel selbst wird von keinem Endpoint zurückgegeben — gespeichert ist nur sein Hash, ein verlorener Schlüssel wird also ersetzt, nicht wiederhergestellt.

Feld	Typ	Beschreibung
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.