Authentification API

Cette page couvre l’API REST publique (/api/v1/*) — celle que vos scripts, pipelines CI ou intégrations appellent. Elle est distincte du flux de connexion navigateur utilisé pour vous authentifier au dashboard (celui-ci repose sur Keycloak/OIDC en coulisses et n’est pas quelque chose dont les clients de l’API ont à se soucier).

Prérequis

L’API publique est réservée au plan Max.

Générer une clé API

1. Allez dans Paramètres → Clés API.
2. Donnez un nom à la clé et, éventuellement, une date d’expiration (laissez vide pour une clé qui n’expire jamais).
3. Cliquez sur « Générer une nouvelle clé ».
4. Copiez la clé immédiatement — elle n’est affichée qu’une seule fois (oks_live_...).

Les clés peuvent être tournées (nouvelle valeur, même entrée) ou révoquées depuis la même page, et une clé qui expire prévient le propriétaire de l’organisation par email à 30, 14 et 7 jours. Voir Sécurité du compte.

Authentifier une requête

Envoyez la clé en tant que Bearer token sur chaque requête :

GET /api/v1/monitors HTTP/1.1
Host: api.okstatus.eu
Authorization: Bearer oks_live_xxxxxxxxxxxxxxxx

curl https://api.okstatus.eu/api/v1/monitors \
  -H "Authorization: Bearer oks_live_xxxxxxxxxxxxxxxx"

Une clé manquante ou mal formée retourne 401 UNAUTHORIZED. Une clé valide mais appartenant à une organisation qui n’est pas sur le plan Max retourne 403 FORBIDDEN.

Limites de débit

Les requêtes sont plafonnées par organisation : 1000 requêtes/heure. Chaque réponse inclut :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1700000000

Dépasser la limite retourne 429 RATE_LIMITED.

Format des erreurs

Chaque réponse d’erreur — sur tous les endpoints — utilise le même format :

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor not found"
  }
}

Ce que couvre l’API

Ressource	Endpoints
Monitors	/monitors, /monitors/{id}, /monitors/{id}/checks, /monitors/{id}/uptime
Incidents	/incidents, /incidents/{id}, /incidents/{id}/resolve
Maintenances	/maintenances, /maintenances/{id}
Pages de statut	/status-pages, /status-pages/{id}
Canaux d’alerte	/alert-channels, /alert-channels/{id}
Instantanés de statut	/status, /status/summary
Organisation	/org

Tous sont sous https://api.okstatus.eu/api/v1. Les schémas de requête et de réponse de chacun sont dans la référence interactive.

Référence interactive

La liste complète et toujours à jour des endpoints (schémas de requête/réponse, essai en direct) se trouve sur la référence interactive OpenAPI. Le spec lui-même (/api/v1/openapi.json) est accessible sans clé, pour pouvoir être utilisé par des outils de génération de code.