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
- Abre Developer › API tokens.
- Elige Create a new token.
- Introduce un nombre, elige los scopes y la caducidad, y confirma con tu contraseña.
- 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.