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. L’export Prometheus est disponible dès Pro, avec une clé Métriques.

Niveaux d’accès

Chaque clé reçoit un niveau d’accès à sa création et le garde quand on la régénère :

Accès	Ce qu’elle permet	Plans
Métriques	GET /api/v1/metrics seulement (export Prometheus)	Pro et au-dessus
Lecture seule	tous les GET de l’API, aucune modification	Max et au-dessus
Complète	lecture et écriture : créer, modifier, supprimer (Terraform, CI)	Max et au-dessus

Donnez à chaque outil la clé la plus restreinte possible : une clé Métriques qui fuite expose les chiffres de vos monitors, une clé Complète qui fuite permet de les supprimer. Une requête au-delà de l’accès de la clé renvoie 403 KEY_SCOPE.

Générer une clé API

1. Allez dans Paramètres → Clés API.
2. Choisissez son Accès (voir ci-dessus), 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 dont l’organisation n’a pas le plan requis par son accès (Max pour Lecture seule et Complète, Pro pour Métriques) retourne 403 FORBIDDEN. Une requête que son accès ne permet pas retourne 403 KEY_SCOPE.

Limites de débit

Les requêtes sont plafonnées par organisation : 5000 requêtes/heure, et environ 150 par minute en rafale. Chaque réponse inclut :

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4998
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
Canaux d’un monitor	/monitors/{id}/alert-channels
Groupes de monitors	/monitor-groups, /monitor-groups/{id}
Agents privés	/private-agents (lecture seule)
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.