API

Jetons d'API

Crée un jeton d'API pour PublicStatus, choisis ses scopes et envoie-le avec tes requêtes.

Dernière mise à jour :

Un jeton d’API permet à un script ou à un autre service d’appeler l’API de PublicStatus en ton nom. Ses scopes décident des données qu’il peut lire ou modifier.

Créer un jeton

  1. Ouvre Developer › API tokens.
  2. Choisis Create a new token.
  3. Saisis un nom, choisis les scopes et l’expiration, puis confirme avec ton mot de passe.
  4. Copie le jeton. Il commence par kpat_ et n’est affiché qu’une seule fois.

Un jeton expire après 90 jours si tu ne choisis pas une autre expiration. L’expiration la plus longue possible est de 3650 jours.

Utiliser le jeton

Envoie le jeton dans l’en-tête Authorization. Les requêtes avec jeton n’ont besoin ni de cookie ni de jeton 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"
  }
}'

Scopes

Chaque scope a deux niveaux. read autorise les handlers de lecture. write autorise tout ce que read autorise, plus les handlers d’écriture.

Scope Droit Handlers
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 de requêtes

Chaque jeton peut envoyer 120 requêtes par tranche de 60 secondes. Au-delà, l’API répond 429 pat_rate_limited.

Les jetons d’API sont disponibles à partir de l’offre Team.

Erreurs

Statut HTTP Code Cause
401 missing_token L’en-tête Authorization est absent.
401 invalid_token Le jeton est inconnu, révoqué ou expiré.
403 access_denied Il manque au jeton le scope pour ce handler.
403 access_denied L’endpoint n’accepte pas les jetons. Les jetons ne fonctionnent que sur les endpoints de l’API.
429 pat_rate_limited Trop de requêtes avec ce jeton.
403 feature_disabled Les jetons d’API ne font pas partie de ton offre.

Révoquer un jeton

Révoque un jeton dans Developer › API tokens dès que tu ne l’utilises plus. Changer ton mot de passe révoque tous tes jetons. Un jeton agit toujours avec tes rôles actuels. Si tu quittes le compte ou si ton utilisateur est supprimé, il cesse de fonctionner.

Sécurité

  • Traite un jeton comme un mot de passe. Garde-le dans un coffre à secrets, jamais dans le code, un dépôt, une app ou une page web, ni dans un log.
  • Donne à chaque script son propre jeton, avec seulement les scopes dont il a besoin.
  • Révoque les jetons que tu n’utilises plus. Révoque un jeton immédiatement s’il a pu fuiter.