API

Tokens de API

Crea un token de API para PublicStatus, elige sus scopes y envíalo con tus peticiones.

Última actualización:

Un token de API permite que un script u otro servicio llame a la API de PublicStatus en tu nombre. Sus scopes deciden qué datos puede leer o cambiar.

Crear un token

  1. Abre Developer › API tokens.
  2. Elige Create a new token.
  3. Introduce un nombre, elige los scopes y la caducidad, y confirma con tu contraseña.
  4. Copia el token. Empieza por kpat_ y se muestra una sola vez.

Un token caduca a los 90 días si no eliges otra caducidad. La caducidad máxima posible es de 3650 días.

Usar el token

Envía el token en la cabecera Authorization. Las peticiones con token no necesitan cookie ni 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"
  }
}'

Scopes

Cada scope tiene dos niveles. read permite los handlers de lectura. write permite todo lo que permite read y además los handlers de escritura.

Scope Permiso 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

Límite de peticiones

Cada token puede enviar 120 peticiones cada 60 segundos. Por encima, la API responde 429 pat_rate_limited.

Los tokens de API están disponibles desde el plan Team.

Errores

Estado HTTP Código Causa
401 missing_token Falta la cabecera Authorization.
401 invalid_token El token es desconocido, está revocado o ha caducado.
403 access_denied Al token le falta el scope para este handler.
403 access_denied El endpoint no acepta tokens. Los tokens solo funcionan en los endpoints de la API.
429 pat_rate_limited Demasiadas peticiones con este token.
403 feature_disabled Los tokens de API no forman parte de tu plan.

Revocar un token

Revoca un token en Developer › API tokens en cuanto dejes de usarlo. Al cambiar tu contraseña se revocan todos tus tokens. Un token actúa siempre con tus roles actuales. Si abandonas la cuenta o se elimina tu usuario, deja de funcionar.

Seguridad

  • Trata un token como una contraseña. Guárdalo en un almacén de secretos, nunca en el código, en un repositorio, en una app o página web ni en un log.
  • Da a cada script su propio token, solo con los scopes que necesita.
  • Revoca los tokens que ya no uses. Revoca un token de inmediato si puede haberse filtrado.