Authenticatie

Bearer-tokens

Elke route behalve /health, /api/v1/openapi.json, /api/v1/docs en /api/v1/token vereist een bearer-token.

Authorization: Bearer <token>

Tokens worden bewaard in de sleutelhanger van het besturingssysteem, met een label, een scope en een optionele levensduur. Deze documentatie beschrijft niet de vorm van een token — behandel het als een ondoorzichtige tekenreeks, en bewaar het zoals je elk ander geheim bewaart.

Er een aanmaken

Vanaf de commandoregel:

tcc config create-api-token --scope full

Of via HTTP, vanaf de machine zelf:

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

Die route vereist zelf geen token. Ze is alleen veilig omdat de server aan loopback bindt, dus alles wat haar kan bereiken bevindt zich al op de machine. Het antwoord bevat het token en zijn scope.

Via HTTP is dat antwoord het enige moment waarop het token wordt getoond: GET /api/v1/api-tokens somt ze gemaskeerd op. De commandoregel kan een opgeslagen token nog wel tonen aan de persoon achter de machine, wat de reden is waarom de sleutelhanger de grens is die ertoe doet.

GET en POST op /api/v1/api-tokens sommen tokens op en maken ze aan; DELETE /api/v1/api-tokens/{id} trekt er een in.

De drie scopes

Een token draagt een van drie scopes. De scope wordt centraal gehandhaafd, op basis van de HTTP-methode en het pad, voordat een handler draait.

Scope	Mag
read	Elke GET buiten de beheerroutes
write	Hetzelfde, plus schrijven naar je eigen gegevens
full	Alles, inclusief organisatiebeheer en tokenbeheer

Beheer betekent /api/v1/org/members, /api/v1/org/groups, /api/v1/org/alerts en /api/v1/api-tokens. Die vereisen full op elke methode, ook lezen. Verder heeft niets full nodig — de rest van de organisatieroutes, met activiteit en analyse erbij, zijn gewone leesroutes.

Geef een integratie de smalste scope die haar taak doet. Een rapportagescript wil read; het wordt dan geweigerd zodra het ooit iets probeert te verwijderen.

Weigeringen

Een ontbrekend of ongeldig token geeft 401. Een geldig token met een te smalle scope geeft 403, met een body die de scope die je hebt, het verzoek dat je deed, en de scope die het nodig heeft noemt:

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

Een token intrekken werkt onmiddellijk: verwijder het via /api/v1/api-tokens/{id} en het volgende verzoek dat het meedraagt wordt geweigerd.