Obexal Docs

Docs/Administration/API d'administration et jetons

API d'administration et jetons d'API

Automatisez votre organisation avec des jetons d'API scopés par permissions RBAC et un contrat OpenAPI 3.1 public.

Tout ce que fait la console Obexal passe par la même API HTTP, sous /v1/admin/*. Les jetons d'API d'administration permettent à vos scripts, pipelines CI et intégrations d'appeler cette API en machine-to-machine, avec des permissions plafonnées par des scopes RBAC. Tous les exemples utilisent https://accounts.obexal.com ; si votre organisation utilise un domaine personnalisé, remplacez-le.

Jetons d'API et scopes

Un jeton d'API d'administration est un secret propre au tenant, commençant par le préfixe obx_. Il porte un sous-ensemble figé de permissions RBAC (ses scopes), choisi à la création :

  • Les scopes doivent être un sous-ensemble des permissions du créateur au moment de l'émission. En demander davantage est refusé avec 403 (anti-escalade, fermé par défaut).
  • Le secret brut n'est montré qu'une seule fois, à la création. Obexal ne conserve que son empreinte SHA-256, plus les 12 premiers caractères comme préfixe d'affichage dans les listes.
  • Un jeton peut porter une date d'expiration (expiresAt, RFC 3339). Un jeton expiré, révoqué ou inconnu est rejeté avec 401.
  • Chaque action effectuée avec un jeton est inscrite au journal d'audit, attribuée au jeton et à son créateur humain.

Les scopes viennent du catalogue de permissions, le même que celui des rôles et RBAC :

ScopeAutorise
users:viewLire l'annuaire (utilisateurs, identités unifiées)
apps:manageCréer, modifier et supprimer des clients OAuth
audit:viewConsulter le journal d'audit
members:manageAttribuer des rôles, suspendre, réactiver, déconnecter
tenant:manageParamètres du tenant : marque, domaines, webhooks, politiques, jetons d'API
roles:manageDéfinir des rôles personnalisés
groups:manageGérer les groupes d'utilisateurs

Créer un jeton

La gestion des jetons d'API exige la permission tenant:manage. Créez votre premier jeton dans la console (Administration, Jetons d'API) : vous le nommez, cochez ses scopes et posez éventuellement une expiration. Une fois en possession d'un jeton portant tenant:manage, vous pouvez automatiser la gestion des jetons elle-même :

curl -X POST https://accounts.obexal.com/v1/admin/api-tokens \
  -H "Authorization: Bearer $OBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","scopes":["users:view","apps:manage"],"expiresAt":"2027-01-01T00:00:00Z"}'
{
  "token": "obx_3Qd1f8nc2mK9xZv7...",
  "tokenInfo": {
    "id": "tok_01hzx...",
    "name": "ci-deploy",
    "prefix": "obx_3Qd1f8nc",
    "scopes": ["users:view", "apps:manage"],
    "createdAt": "2026-07-02T09:15:00Z",
    "expiresAt": "2027-01-01T00:00:00Z"
  }
}
Attention

La valeur token n'est renvoyée qu'une seule fois et n'est pas récupérable. Rangez-la immédiatement dans votre gestionnaire de secrets.

Appeler l'API avec un jeton

Envoyez le secret dans l'en-tête Authorization :

curl https://accounts.obexal.com/v1/admin/users \
  -H "Authorization: Bearer $OBX_TOKEN"

Les requêtes authentifiées par un Bearer obx_ ne portent aucun cookie de session : il n'y a donc pas de vecteur CSRF, et elles sont exemptées du double-submit CSRF que les sessions navigateur doivent effectuer sur les endpoints de mutation. L'horodatage lastUsedAt du jeton est rafraîchi à chaque usage, ce qui aide à repérer les identifiants dormants.

Les appels hors scope sont refusés

L'autorisation est décidée par les scopes figés du jeton, jamais par le rôle courant du créateur. Un jeton scopé users:view ne peut pas, par exemple, créer un webhook (qui exige tenant:manage) :

curl -X POST https://accounts.obexal.com/v1/admin/webhooks \
  -H "Authorization: Bearer $OBX_READONLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.eu/obexal","events":["user.created"]}'
# 403 {"error":{"code":"forbidden","message":"..."}}

La même règle anti-escalade s'applique à la création : demander un scope que vous ne détenez pas vous-même renvoie 403.

Lister et révoquer les jetons

# Lister (métadonnées seulement, jamais le secret)
curl https://accounts.obexal.com/v1/admin/api-tokens \
  -H "Authorization: Bearer $OBX_TOKEN"
# 200 {"tokens":[{"id":"...","name":"ci-deploy","prefix":"obx_3Qd1f8nc","scopes":[...],"lastUsedAt":"..."}],
#      "availableScopes":["users:view","apps:manage","audit:view","members:manage","tenant:manage","roles:manage","groups:manage"]}

# Révoquer (immédiat, idempotent)
curl -X DELETE https://accounts.obexal.com/v1/admin/api-tokens/tok_01hzx... \
  -H "Authorization: Bearer $OBX_TOKEN"
# 204 No Content

Un jeton révoqué échoue dès la requête suivante. La révocation est inscrite au journal d'audit.

Le contrat OpenAPI 3.1

La surface machine est décrite par un document OpenAPI 3.1 public, servi sans authentification :

curl https://accounts.obexal.com/v1/openapi.json

Il couvre 18 routes regroupées en 5 tags : jetons d'API, agents IA, annuaire, accès conditionnel et policy-as-code. Donnez-le à vos générateurs de code, clients d'API ou passerelles. Les résumés et descriptions du contrat sont rédigés en français.

Prochaines étapes