Authentifizierung

Bearer-Token

Jede Route außer /health, /api/v1/openapi.json, /api/v1/docs und /api/v1/token verlangt ein Bearer-Token.

Authorization: Bearer <token>

Token liegen im Schlüsselbund des Betriebssystems, mit einer Bezeichnung, einer Berechtigungsstufe und einer optionalen Gültigkeitsdauer. Diese Dokumentation beschreibt nicht die Form eines Tokens — behandle es als undurchsichtige Zeichenkette und bewahre es so auf wie jedes andere Geheimnis.

Eins bekommen

Über die Kommandozeile:

tcc config create-api-token --scope full

Oder über HTTP, von der Maschine selbst aus:

POST /api/v1/token
{ "name": "my-integration", "scope": "full" }

Diese Route braucht kein eigenes Token. Sie ist nur deshalb sicher, weil der Server an Loopback bindet, sodass alles, was sie erreichen kann, bereits auf der Maschine läuft. Die Antwort trägt das Token und seine Berechtigungsstufe.

Über HTTP ist diese Antwort das einzige Mal, dass das Token gezeigt wird: GET /api/v1/api-tokens listet Token nur maskiert. Die Kommandozeile kann ein gespeichertes Token der Person an der Maschine weiterhin offenlegen, weshalb der Schlüsselbund die eigentliche Grenze ist.

GET und POST auf /api/v1/api-tokens listen und prägen Token; DELETE /api/v1/api-tokens/{id} widerruft eins.

Die drei Berechtigungsstufen

Ein Token trägt eine von drei Berechtigungsstufen. Sie wird zentral durchgesetzt, anhand der HTTP-Methode und des Pfads, bevor ein Handler läuft.

Berechtigung	Darf
read	Jedes GET außerhalb der Verwaltungsrouten
write	Dasselbe, dazu Schreibzugriffe auf die eigenen Daten
full	Alles, einschließlich Organisationsverwaltung und Token-Verwaltung

Verwaltung meint /api/v1/org/members, /api/v1/org/groups, /api/v1/org/alerts und /api/v1/api-tokens. Diese brauchen full bei jeder Methode, auch beim Lesen. Nichts sonst braucht full — die übrigen Organisationsrouten, darunter Aktivität und Analytics, sind gewöhnliche Lesezugriffe.

Gib einer Integration die engste Berechtigungsstufe, die für ihre Aufgabe reicht. Ein Berichtsskript will read; es wird dann abgewiesen, sobald es versucht, etwas zu löschen.

Abweisungen

Ein fehlendes oder ungültiges Token führt zu 401. Ein gültiges Token, dessen Berechtigung zu eng ist, führt zu 403, mit einem Rumpf, der die vorhandene Berechtigung, die gestellte Anfrage und die benötigte Berechtigung nennt:

{
  "error": "insufficient_scope",
  "message": "Token scope 'read' cannot perform DELETE /api/v1/tags/abc. Requires write or full scope.",
  "required_scope": "write or full"
}

Ein Token zu widerrufen wirkt sofort: Lösche es über /api/v1/api-tokens/{id}, und die nächste Anfrage damit wird abgewiesen.