Autenticación de la API

nota

La API pública v1 está disponible en los planes Pro y Enterprise. Si tu cuenta está en el plan gratuito, los tokens son válidos pero todas las peticiones devolverán 403 plan_feature_disabled.

Tokens Bearer

Todas las peticiones a la API v1 requieren un header Authorization:

Authorization: Bearer <tu-token>

Los tokens se generan desde el panel en Cuenta → API → Tokens. Cada token tiene un nombre, scopes y opcionalmente una fecha de expiración.

Scopes

Cada token solo puede hacer lo que sus scopes permiten. Si una petición requiere un scope que el token no tiene, la API responde 403 forbidden.

Scope	Permite
monitors:read	Listar y consultar monitores
monitors:write	Crear, actualizar y eliminar monitores
checks:read	Consultar historial de checks por monitor
incidents:read	Listar y consultar incidentes
status_pages:read	Listar y consultar páginas de estado
status_pages:write	Crear, actualizar y eliminar páginas de estado

Rate limiting

El límite de peticiones por minuto depende de tu plan:

Plan	Peticiones por minuto
Pro	120
Enterprise	300

Los headers de respuesta siempre incluyen el estado actual:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1747180860

Si superas el límite recibes 429 rate_limit_exceeded con el header Retry-After indicando cuántos segundos esperar.

El cuerpo de cada respuesta también incluye estos valores en meta.rate_limit.

Formato de respuesta

Item único:

{
  "data": { "id": "42", "type": "monitor", "attributes": { ... } },
  "meta": { "request_id": "abc123", "rate_limit": { "limit": 120, "remaining": 117, "reset": 1747180860, "retry_after": null } }
}

Listado paginado:

{
  "data": [ ... ],
  "pagination": { "page": 1, "per_page": 25, "total": 80, "total_pages": 4 },
  "meta": { "request_id": "abc123", "rate_limit": { ... } }
}

Error:

{
  "error": { "code": "not_found", "message": "Monitor no encontrado.", "details": [] },
  "meta": { "request_id": "abc123" }
}

Códigos de error comunes

HTTP	code	Motivo
401	unauthorized	Token ausente, inválido o expirado
403	forbidden	El token no tiene el scope requerido
403	plan_feature_disabled	La API pública no está disponible en tu plan
404	not_found	Recurso no encontrado o no pertenece a tu cuenta
400	bad_request	Cuerpo de petición vacío o malformado
422	validation_error	Datos inválidos; details contiene los errores por campo
422	quota_exceeded	Límite de recursos de tu plan alcanzado
429	rate_limit_exceeded	Demasiadas peticiones por minuto
500	server_error	Error interno inesperado

Rotación de tokens

Rota los tokens periódicamente para reducir el impacto de una filtración. El flujo recomendado es:

1. Crea un nuevo token con los mismos scopes desde Cuenta → API → Tokens.
2. Actualiza la integración o el sistema que lo usa con el nuevo token.
3. Verifica que la integración funciona correctamente con el nuevo token.
4. Revoca el token antiguo desde el panel.

Si creas tokens con fecha de expiración, el sistema los invalida automáticamente en esa fecha. El header de respuesta incluye la fecha de expiración en el campo expires_at cuando aplica.

---

Buenas prácticas

• Crea tokens con el mínimo de scopes necesario.
• Rota los tokens periódicamente o usa tokens con fecha de expiración.
• No incluyas tokens en código fuente; usa variables de entorno o gestores de secretos.
• Respeta el header Retry-After ante un 429 en lugar de reintentar inmediatamente.
• Usa un nombre descriptivo por token para saber qué integración lo usa (ej. «CI/CD pipeline», «Dashboard externo»).