Admin API reference

The programmable administration API: obx_ token authentication, RBAC permissions, every documented operation, and the map of console routes.

The administration API is served on your sign-in domain (https://accounts.obexal.com by default; a custom domain replaces that host). Its machine-to-machine contract is published as an OpenAPI 3.1 document. For a guided introduction, see Admin API.

Authentication

Machine-to-machine calls authenticate with an admin API token, a bearer secret prefixed obx_:

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

Tokens are created in the console (Administration, API tokens) or via POST /v1/admin/api-tokens. The raw secret is returned once and never again.
Requested scopes must be a subset of the creator's permissions (no privilege escalation).
Expiry is optional; revocation takes effect on the next request (fail closed).
No cookies are involved, so these calls are exempt from CSRF.
401 means the token is missing, invalid, expired or revoked; 403 means the required permission is not in the token's scopes.

Permissions

Each operation requires one RBAC permission, checked against the token's frozen scopes:

Permission	Grants
`users:view`	Read the directory and the unified identity register
`apps:manage`	Manage applications and AI agents (governance, identity, secrets, anomalies)
`audit:view`	Read the audit log
`members:manage`	Manage members and invitations
`tenant:manage`	Tenant settings, API tokens, access and risk policies, policy as code
`roles:manage`	Manage custom RBAC roles
`groups:manage`	Manage groups and their app assignments

The OpenAPI contract

The full contract is downloadable, without authentication, from your own instance:

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

Import it into your API client or code generator. The operations in the sections below are exactly the ones it documents: they are the stable machine-to-machine surface.

API tokens

Method	Path	Permission	Description
GET	`/v1/admin/api-tokens`	`tenant:manage`	List tokens (metadata only, never the secret) plus assignable scopes
POST	`/v1/admin/api-tokens`	`tenant:manage`	Create a token; the raw secret is returned once
DELETE	`/v1/admin/api-tokens/{id}`	`tenant:manage`	Revoke a token immediately (idempotent)

AI agents

Method	Path	Permission	Description
GET	`/v1/admin/agents`	`apps:manage`	Inventory of agents with governance, identity, status and review state
PUT	`/v1/admin/agents/{clientId}/policy`	`apps:manage`	Set the kill switch and ceilings (token TTL, scopes, audiences)
DELETE	`/v1/admin/agents/{clientId}/policy`	`apps:manage`	Reset the agent policy to defaults
PUT	`/v1/admin/agents/{clientId}/identity`	`apps:manage`	Set the human owner and the agent expiry date
POST	`/v1/admin/agents/{clientId}/review`	`apps:manage`	Attest an access review (timestamps it)
POST	`/v1/admin/agents/{clientId}/secret`	`apps:manage`	Rotate the client_secret; the new secret is returned once
GET	`/v1/admin/agents/anomalies`	`apps:manage`	List behavior anomalies (`?all=true` includes acknowledged ones)
POST	`/v1/admin/agents/anomalies/{id}/ack`	`apps:manage`	Acknowledge an anomaly

See Governance policy and Kill switch and anomalies for the concepts behind these operations.

Method	Path	Permission	Description
GET	`/v1/admin/users`	`users:view`	List the users of the tenant
GET	`/v1/admin/identities`	`users:view`	Unified register of humans, services and AI agents, with owner, status and anomalies

Conditional access

Method	Path	Permission	Description
GET	`/v1/admin/access-policy/versions`	`tenant:manage`	Versioned history of the access policy, most recent first
POST	`/v1/admin/access-policy/versions/{id}/restore`	`tenant:manage`	Roll back to a snapshot (creates a new current version)
POST	`/v1/admin/access-policy/simulate`	`tenant:manage`	Evaluate a candidate policy against recent sign-ins; applies nothing
GET	`/v1/admin/risk-policy`	`tenant:manage`	Read the risk-based access policy
PUT	`/v1/admin/risk-policy`	`tenant:manage`	Set risk scoring thresholds (step-up MFA, deny)

Policy as code

Method	Path	Permission	Description
GET	`/v1/admin/config`	`tenant:manage`	Export the governance configuration as a declarative bundle
POST	`/v1/admin/config/plan`	`tenant:manage`	Diff a candidate bundle against the current state; applies nothing
POST	`/v1/admin/config/apply`	`tenant:manage`	Apply a bundle (`?prune=true` also deletes roles absent from it)

See Policy as code for the GitOps workflow.

Console routes outside the OpenAPI contract

The admin console uses many more routes under /v1/*. They authenticate with a browser session (plus a CSRF header on mutations); most of them also accept an admin API token carrying the matching permission, but only the operations above form the documented machine contract, and the shapes below can evolve with the console.

Area	Routes
Members	`GET /v1/admin/members`, `PUT/DELETE /v1/admin/members/{userId}`
User lifecycle	`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}`
Groups	`GET/POST /v1/admin/groups`, `PUT/DELETE /v1/admin/groups/{id}`, members under `/v1/admin/groups/{id}/members`, app assignments under `/v1/admin/groups/{id}/apps`
Custom roles	`GET/POST /v1/admin/roles`, `PUT/DELETE /v1/admin/roles/{key}`
Tenant and branding	`GET/PATCH /v1/admin/tenant`, `PUT/DELETE /v1/admin/tenant/logo`
Custom domains	`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 or JSON)
Access and password policies	`GET/PUT /v1/admin/access-policy`, `GET/PUT /v1/admin/password-policy`, group overrides under `/v1/admin/password-policy/groups`, `GET/POST /v1/admin/ip-blocks`, `DELETE /v1/admin/ip-blocks/{ip}`
SAML	`GET/PUT /v1/admin/saml` (inbound connection), `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}` (inbound tokens), `GET/POST /v1/admin/scim-targets`, `PUT/DELETE /v1/admin/scim-targets/{id}`, `POST /v1/admin/scim-targets/{id}/sync` (outbound)
LDAP	`GET/PUT/DELETE /v1/admin/ldap`
Social connections	`GET/POST /v1/admin/social/connections`, `DELETE /v1/admin/social/connections/{provider}`
Security dashboards	`GET /v1/admin/security-stats`, `GET /v1/admin/security-incidents`, `POST /v1/admin/security-incidents/{id}/ack`, `GET /v1/admin/growth-stats`
Agent delegations	`GET /v1/admin/agents/delegations` (forensic journal of who acted on whose behalf)
Applications (OAuth clients)	`GET/POST /v1/applications`, `GET/PATCH/DELETE /v1/applications/{clientId}`, integration catalog under `/v1/integrations`

Pagination and errors

List endpoints accept ?limit (default 100, maximum 500) and ?offset; the audit log adds ?q (full-text) and ?outcome filters. Errors use the JSON envelope {"error": {"code", "message"}}: codes, rate limits and caps are documented in Errors and limits.