Autenticazione

Bearer token

Ogni rotta tranne /health, /api/v1/openapi.json, /api/v1/docs e /api/v1/token richiede un bearer token.

Authorization: Bearer <token>

I token sono conservati nel portachiavi del sistema operativo, con un’etichetta, uno scope e una durata opzionale. Questa documentazione non descrive la forma di un token — trattalo come una stringa opaca, e conservalo come conservi qualsiasi altro segreto.

Ottenerne uno

Dalla riga di comando:

tcc config create-api-token --scope full

Oppure via HTTP, dalla macchina stessa:

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

Quella rotta non richiede un proprio token. È sicura solo perché il server si lega al loopback, quindi tutto ciò che può raggiungerla è già sulla macchina. La risposta contiene il token e il suo scope.

Via HTTP quella risposta è l’unica volta in cui il token viene mostrato: GET /api/v1/api-tokens li elenca mascherati. La riga di comando può ancora rivelare uno memorizzato alla persona alla macchina, motivo per cui il portachiavi è il confine che conta.

GET e POST su /api/v1/api-tokens elencano e generano token; DELETE /api/v1/api-tokens/{id} ne revoca uno.

I tre scope

Un token porta uno dei tre scope. Lo scope viene applicato centralmente, dal metodo HTTP e dal percorso, prima che un handler venga eseguito.

Scope	Può fare
read	Qualsiasi GET fuori dalle rotte di gestione
write	Lo stesso, più scritture sui propri dati
full	Tutto, inclusa la gestione dell’organizzazione e dei token

Gestione significa /api/v1/org/members, /api/v1/org/groups, /api/v1/org/alerts e /api/v1/api-tokens. Quelle richiedono full su ogni metodo, letture incluse. Nient’altro richiede full — il resto delle rotte dell’organizzazione, attività e analytics comprese, sono letture ordinarie.

Dai a un’integrazione lo scope più stretto che svolge il suo compito. Uno script di reportistica vuole read; verrà quindi rifiutato se prova mai a eliminare qualcosa.

Rifiuti

Un token mancante o non valido è 401. Un token valido il cui scope è troppo stretto è 403, con un corpo che nomina lo scope che hai, la richiesta che hai fatto e lo scope che servirebbe:

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

Revocare un token è immediato: eliminalo tramite /api/v1/api-tokens/{id} e la richiesta successiva che lo porta viene rifiutata.