API

Token API

Crea un token API per PublicStatus, scegli i suoi scope e invialo con le tue richieste.

Ultimo aggiornamento:

Un token API permette a uno script o a un altro servizio di chiamare l’API di PublicStatus a tuo nome. I suoi scope decidono quali dati può leggere o modificare.

Creare un token

  1. Apri Developer › API tokens.
  2. Scegli Create a new token.
  3. Inserisci un nome, scegli gli scope e la scadenza e conferma con la tua password.
  4. Copia il token. Inizia con kpat_ e viene mostrato una sola volta.

Un token scade dopo 90 giorni se non scegli un’altra scadenza. La scadenza massima possibile è di 3650 giorni.

Usare il token

Invia il token nell’header Authorization. Le richieste con token non richiedono cookie né token CSRF.

curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:component:detail",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}'

Scope

Ogni scope ha due livelli. read consente gli handler di lettura. write consente tutto ciò che consente read più gli handler di scrittura.

Scope Permesso Handler
components (Components) components:read publicstatus:query:component:detail, publicstatus:query:component:list
components (Components) components:write publicstatus:write:component:create, publicstatus:write:component:delete, publicstatus:write:component:update
incidents (Incidents) incidents:read publicstatus:query:incident:detail, publicstatus:query:incident:list, publicstatus:query:incident:updates
incidents (Incidents) incidents:write publicstatus:write:incident:open, publicstatus:write:incident:post-update, publicstatus:write:incident:resolve, publicstatus:write:incident:update
maintenance (Maintenance) maintenance:read publicstatus:query:maintenance:detail, publicstatus:query:maintenance:list
maintenance (Maintenance) maintenance:write publicstatus:write:maintenance:cancel, publicstatus:write:maintenance:complete, publicstatus:write:maintenance:schedule, publicstatus:write:maintenance:start
monitors (Monitors) monitors:read publicstatus:query:monitor:detail, publicstatus:query:monitor:list, publicstatus:query:monitor:uptime-public
monitors (Monitors) monitors:write publicstatus:write:monitor:check-now, publicstatus:write:monitor:create, publicstatus:write:monitor:delete, publicstatus:write:monitor:mint-heartbeat-token, publicstatus:write:monitor:update
webhooks (Webhooks) webhooks:read publicstatus:query:webhook-subscriber:detail, publicstatus:query:webhook-subscriber:list
webhooks (Webhooks) webhooks:write publicstatus:write:webhook-subscriber:create, publicstatus:write:webhook-subscriber:delete, publicstatus:write:webhook-subscriber:reactivate, publicstatus:write:webhook-subscriber:rotate-secret, publicstatus:write:webhook-subscriber:update

Limite di richieste

Ogni token può inviare 120 richieste ogni 60 secondi. Oltre, l’API risponde 429 pat_rate_limited.

I token API sono disponibili dal piano Team.

Errori

Stato HTTP Codice Causa
401 missing_token Manca l’header Authorization.
401 invalid_token Il token è sconosciuto, revocato o scaduto.
403 access_denied Al token manca lo scope per questo handler.
403 access_denied L’endpoint non accetta token. I token funzionano solo sugli endpoint dell’API.
429 pat_rate_limited Troppe richieste con questo token.
403 feature_disabled I token API non fanno parte del tuo piano.

Revocare un token

Revoca un token in Developer › API tokens non appena smetti di usarlo. Cambiare la password revoca tutti i tuoi token. Un token agisce sempre con i tuoi ruoli attuali. Se lasci l’account o il tuo utente viene eliminato, smette di funzionare.

Sicurezza

  • Tratta un token come una password. Conservalo in un archivio di segreti, mai nel codice, in un repository, in un’app o pagina web o in un log.
  • Dai a ogni script il suo token, con solo gli scope di cui ha bisogno.
  • Revoca i token che non usi più. Revoca subito un token se potrebbe essere trapelato.