Admin API and API tokens

Automate your organization with RBAC-scoped admin API tokens and a public OpenAPI 3.1 contract.

Everything the Obexal console does goes through the same HTTP API, under /v1/admin/*. Admin API tokens let your scripts, CI pipelines and integrations call that API machine-to-machine, with permissions capped by RBAC scopes. All examples use https://accounts.obexal.com; if your organization uses a custom domain, replace it accordingly.

API tokens and scopes

An admin API token is a per-tenant secret starting with the prefix obx_. It carries a frozen subset of RBAC permissions (its scopes), chosen at creation:

Scopes must be a subset of the creator's own permissions at issuance time. Requesting more is refused with 403 (anti-escalation, fail-closed).
The raw secret is shown once, at creation. Obexal persists only its SHA-256 hash, plus the first 12 characters as a display prefix for listings.
A token can carry an expiration date (expiresAt, RFC 3339). An expired, revoked or unknown token is rejected with 401.
Every action performed with a token is written to the audit log, attributed to the token and its human creator.

Scopes come from the permission catalog, the same one used by roles and RBAC:

Scope	Grants
`users:view`	Read the directory (users, unified identities)
`apps:manage`	Create, modify and delete OAuth clients
`audit:view`	Read the audit log
`members:manage`	Assign roles, suspend, reactivate, force logout
`tenant:manage`	Tenant settings: branding, domains, webhooks, policies, API tokens
`roles:manage`	Define custom roles
`groups:manage`	Manage user groups

Create a token

Managing API tokens requires the tenant:manage permission. Create your first token in the console (Administration, API tokens): you name it, tick its scopes and optionally set an expiration. Once you hold a token with tenant:manage, you can automate token management itself:

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"
  }
}

Warning

The token value is returned only once and cannot be recovered. Store it in your secret manager immediately.

Call the API with a token

Send the secret in the Authorization header:

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

Requests authenticated by a Bearer obx_ token carry no session cookie, so there is no CSRF vector: they are exempt from the CSRF double-submit that browser sessions must perform on mutating endpoints. The token's lastUsedAt timestamp is refreshed on each use, which helps you spot stale credentials.

Out-of-scope calls are refused

Authorization is decided by the token's frozen scopes, never by the creator's current role. A token scoped users:view cannot, for example, create a webhook (which needs 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":"..."}}

The same anti-escalation rule applies at creation time: asking for a scope you do not hold yourself returns 403.

List and revoke tokens

# List (metadata only, never the 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"]}

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

A revoked token fails on the next request. Revocation is recorded in the audit log.

The OpenAPI 3.1 contract

The machine-facing surface is described by a public OpenAPI 3.1 document, served without authentication:

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

It covers 18 routes grouped in 5 tags: API tokens, AI agents, directory, conditional access and policy-as-code. Feed it to your code generators, API clients or gateway. Summaries and descriptions in the contract are written in French.

Next steps

Policy as code: version your governance in Git and apply it from CI with an API token.
Admin API reference: the endpoint-by-endpoint reference.