Authentifizierung & Scopes

Ein Schlüssel gehört genau einer Organisation und darf nur, was seine Scopes erlauben.

API-Schlüssel

Header: Authorization: Bearer capi_… Der Schlüssel identifiziert Organisation und Zugang; die Organisation steckt im Schlüssel, nie im Aufruf. Schlüssel können ablaufen und auf IP-Adressen beschränkt sein.

Scopes

Muster resource:read und resource:write (Schreiben schliesst Lesen ein), z. B. contacts:read, invoices:write. Fehlt ein Scope, antwortet die API mit 403 und nennt die verlangten Scopes.

http

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://www.claritos.io/developers/errors#insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient-scope",
  "requiredScopes": ["contacts:write"],
  "instance": "6f1c…"
}

Rotation

Rotieren erzeugt einen neuen Schlüssel mit denselben Rechten; der alte läuft 24 Stunden weiter. Widerruf wirkt sofort.

Sicherheit

Wir speichern nur einen sha256-Abdruck. Schlüssel nie in Client-Code, Repositories oder Logs ablegen. Bei Verdacht sofort rotieren oder widerrufen.