Référence de l'API d'administration

L'API d'administration programmable : authentification par jeton obx_, permissions RBAC, toutes les opérations documentées et la carte des routes de la console.

L'API d'administration est servie sur votre domaine de connexion (https://accounts.obexal.com par défaut ; un domaine personnalisé remplace cet hôte). Son contrat machine-to-machine est publié sous forme de document OpenAPI 3.1. Pour une introduction guidée, voir API d'administration.

Authentification

Les appels machine-to-machine s'authentifient avec un jeton d'API d'administration, un secret bearer préfixé obx_ :

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

Les jetons se créent dans la console (Administration, Jetons d'API) ou via POST /v1/admin/api-tokens. Le secret brut n'est renvoyé qu'une seule fois.
Les scopes demandés doivent être un sous-ensemble des permissions du créateur (aucune escalade de privilèges).
L'expiration est optionnelle ; la révocation prend effet à la requête suivante (fail closed).
Aucun cookie n'est impliqué : ces appels sont exemptés de CSRF.
401 signifie jeton absent, invalide, expiré ou révoqué ; 403 signifie que la permission requise n'est pas dans les scopes du jeton.

Permissions

Chaque opération exige une permission RBAC, vérifiée contre les scopes figés du jeton :

Permission	Donne accès à
`users:view`	Lecture de l'annuaire et du registre unifié des identités
`apps:manage`	Gestion des applications et des agents IA (gouvernance, identité, secrets, anomalies)
`audit:view`	Lecture du journal d'audit
`members:manage`	Gestion des membres et des invitations
`tenant:manage`	Paramètres du tenant, jetons d'API, politiques d'accès et de risque, policy as code
`roles:manage`	Gestion des rôles RBAC personnalisés
`groups:manage`	Gestion des groupes et de leurs affectations d'applications

Le contrat OpenAPI

Le contrat complet est téléchargeable, sans authentification, depuis votre propre instance :

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

Importez-le dans votre client d'API ou votre générateur de code. Les opérations des sections suivantes sont exactement celles qu'il documente : c'est la surface machine-to-machine stable.

Jetons d'API

Méthode	Chemin	Permission	Description
GET	`/v1/admin/api-tokens`	`tenant:manage`	Liste les jetons (métadonnées seulement, jamais le secret) et les scopes assignables
POST	`/v1/admin/api-tokens`	`tenant:manage`	Crée un jeton ; le secret brut est renvoyé une seule fois
DELETE	`/v1/admin/api-tokens/{id}`	`tenant:manage`	Révoque un jeton immédiatement (idempotent)

Agents IA

Méthode	Chemin	Permission	Description
GET	`/v1/admin/agents`	`apps:manage`	Inventaire des agents avec gouvernance, identité, statut et état de revue
PUT	`/v1/admin/agents/{clientId}/policy`	`apps:manage`	Définit le kill switch et les plafonds (TTL de jeton, scopes, audiences)
DELETE	`/v1/admin/agents/{clientId}/policy`	`apps:manage`	Réinitialise la politique de l'agent aux défauts
PUT	`/v1/admin/agents/{clientId}/identity`	`apps:manage`	Définit le responsable humain et la date d'expiration de l'agent
POST	`/v1/admin/agents/{clientId}/review`	`apps:manage`	Atteste une revue d'accès (l'horodate)
POST	`/v1/admin/agents/{clientId}/secret`	`apps:manage`	Renouvelle le client_secret ; le nouveau secret est renvoyé une seule fois
GET	`/v1/admin/agents/anomalies`	`apps:manage`	Liste les anomalies de comportement (`?all=true` inclut les acquittées)
POST	`/v1/admin/agents/anomalies/{id}/ack`	`apps:manage`	Acquitte une anomalie

Voir Politique de gouvernance et Kill switch et anomalies pour les concepts derrière ces opérations.

Annuaire

Méthode	Chemin	Permission	Description
GET	`/v1/admin/users`	`users:view`	Liste les utilisateurs du tenant
GET	`/v1/admin/identities`	`users:view`	Registre unifié des humains, services et agents IA, avec responsable, statut et anomalies

Accès conditionnel

Méthode	Chemin	Permission	Description
GET	`/v1/admin/access-policy/versions`	`tenant:manage`	Historique versionné de la politique d'accès, récentes d'abord
POST	`/v1/admin/access-policy/versions/{id}/restore`	`tenant:manage`	Rollback vers un instantané (crée une nouvelle version courante)
POST	`/v1/admin/access-policy/simulate`	`tenant:manage`	Évalue une politique candidate sur les connexions récentes ; n'applique rien
GET	`/v1/admin/risk-policy`	`tenant:manage`	Lit la politique d'accès adaptatif au risque
PUT	`/v1/admin/risk-policy`	`tenant:manage`	Règle les seuils de score de risque (step-up MFA, refus)

Policy as code

Méthode	Chemin	Permission	Description
GET	`/v1/admin/config`	`tenant:manage`	Exporte la configuration de gouvernance en bundle déclaratif
POST	`/v1/admin/config/plan`	`tenant:manage`	Diff d'un bundle candidat contre l'état courant ; n'applique rien
POST	`/v1/admin/config/apply`	`tenant:manage`	Applique un bundle (`?prune=true` supprime aussi les rôles absents)

Voir Policy as code pour le flux GitOps.

Routes de console hors du contrat OpenAPI

La console d'administration utilise beaucoup d'autres routes sous /v1/*. Elles s'authentifient par session navigateur (plus un en-tête CSRF sur les mutations) ; la plupart acceptent aussi un jeton d'API portant la permission correspondante, mais seules les opérations ci-dessus forment le contrat machine documenté, et les formes ci-dessous peuvent évoluer avec la console.

Domaine	Routes
Membres	`GET /v1/admin/members`, `PUT/DELETE /v1/admin/members/{userId}`
Cycle de vie utilisateur	`PUT /v1/admin/users/{userId}`, `POST /v1/admin/users/{userId}/suspend`, `POST /v1/admin/users/{userId}/reactivate`, `POST /v1/admin/users/{userId}/logout`, `POST /v1/admin/users/unlock`
Invitations	`GET/POST /v1/admin/invitations`, `DELETE /v1/admin/invitations/{id}`
Groupes	`GET/POST /v1/admin/groups`, `PUT/DELETE /v1/admin/groups/{id}`, membres sous `/v1/admin/groups/{id}/members`, affectations d'apps sous `/v1/admin/groups/{id}/apps`
Rôles personnalisés	`GET/POST /v1/admin/roles`, `PUT/DELETE /v1/admin/roles/{key}`
Tenant et marque	`GET/PATCH /v1/admin/tenant`, `PUT/DELETE /v1/admin/tenant/logo`
Domaines personnalisés	`GET/POST /v1/admin/domains`, `POST /v1/admin/domains/{domain}/verify`, `DELETE /v1/admin/domains/{domain}`
Webhooks	`GET/POST /v1/admin/webhooks`, `DELETE /v1/admin/webhooks/{id}`
Audit	`GET /v1/admin/audit`, `GET /v1/admin/audit/stream` (SSE), `GET /v1/admin/audit/export` (CSV ou JSON)
Politiques d'accès et de mot de passe	`GET/PUT /v1/admin/access-policy`, `GET/PUT /v1/admin/password-policy`, dérogations par groupe sous `/v1/admin/password-policy/groups`, `GET/POST /v1/admin/ip-blocks`, `DELETE /v1/admin/ip-blocks/{ip}`
SAML	`GET/PUT /v1/admin/saml` (connexion entrante), `GET /v1/admin/saml-idp`, `POST /v1/admin/saml-idp/apps`, `DELETE /v1/admin/saml-idp/apps/{id}`
SCIM	`GET/POST /v1/admin/scim/tokens`, `DELETE /v1/admin/scim/tokens/{id}` (jetons entrants), `GET/POST /v1/admin/scim-targets`, `PUT/DELETE /v1/admin/scim-targets/{id}`, `POST /v1/admin/scim-targets/{id}/sync` (sortant)
LDAP	`GET/PUT/DELETE /v1/admin/ldap`
Connexions sociales	`GET/POST /v1/admin/social/connections`, `DELETE /v1/admin/social/connections/{provider}`
Tableaux de bord sécurité	`GET /v1/admin/security-stats`, `GET /v1/admin/security-incidents`, `POST /v1/admin/security-incidents/{id}/ack`, `GET /v1/admin/growth-stats`
Délégations d'agents	`GET /v1/admin/agents/delegations` (journal forensic de qui a agi au nom de qui)
Applications (clients OAuth)	`GET/POST /v1/applications`, `GET/PATCH/DELETE /v1/applications/{clientId}`, catalogue d'intégrations sous `/v1/integrations`

Pagination et erreurs

Les endpoints de liste acceptent ?limit (défaut 100, maximum 500) et ?offset ; le journal d'audit ajoute les filtres ?q (plein texte) et ?outcome. Les erreurs utilisent l'enveloppe JSON {"error": {"code", "message"}} : les codes, limites de débit et plafonds sont documentés dans Erreurs et limites.