security
Intended Documentation
Enterprise Administration
The tenant-scoped admin surface — trust posture, members and roles, API credential governance, audit evidence export, identity (SSO/SCIM), and emergency containment — with the exact routes, roles, permissions, and failure modes.
Enterprise Administration#
The enterprise admin surface lets a tenant's operators run their own trust boundary: review posture, manage members and roles, govern API credentials, export tamper-evident audit evidence, operate single sign-on and SCIM provisioning, and contain incidents with emergency controls. Every operation is tenant-scoped, permission-checked, and audited.
These endpoints live under the /admin/* prefix (plus /scim/v2/* for provisioning and the /amp · /ebo SSO flows). They are distinct from the runtime authority API (/intent, /authority/*) and use a separate role and permission model — see Roles and Token Governance.
Authentication is shared, authorization is not
Every admin call authenticates through the same fail-closed gate as the rest of the API (see API Authentication): an intended_live_ API key, an Auth0 JWT, or a portal session, plus the x-tenant-id header. But admin routes then resolve an enterprise actor role and check an enterprise admin permission (e.g. tokens:manage, evidence:export, emergency:invoke) — these are not the same as runtime API-key scopes like authority:evaluate.
The admin surface at a glance#
| Area | What you do | Page |
|---|---|---|
| Tenant administration | Read trust overview, environments, member list; change a member's role | Tenant Administration |
| Roles & token governance | Inspect the role/permission matrix; create, list, and revoke API credentials | Roles and Token Governance |
| Audit export | Build, list, and download signed evidence bundles | Audit Export |
| Identity operations | Inspect SSO readiness; run OIDC/SAML flows; provision via SCIM v2 | Identity Provider Operations |
| Emergency controls | Halt/resume a tenant or environment, pause a connector, revoke a credential | Emergency Controls |
Two boundaries every admin call crosses#
- The authentication gate resolves the credential to a verified tenant context and rejects anything it cannot place. A forged or mismatched
x-tenant-id(or a body/querytenantIdthat does not match the credential's tenant) is rejected with403 TENANT_MISMATCHbefore any handler runs. - The enterprise permission check resolves your enterprise role for the tenant and asserts the specific permission the route requires. A missing permission returns
403with{ "error": "FORBIDDEN", "permission": "<name>" }.
tenantId appears in three places — they must agree
For most admin routes the tenant is supplied in the x-tenant-id header and in the query string or request body (tenantId). The route compares them: if the body/query tenantId differs from the header (and the header is present), the request is rejected with 403 TENANT_MISMATCH. Keep all three — credential, header, body/query — pointing at the same tenant.
Failure modes common to every admin route#
| Status | Code | Cause |
|---|---|---|
| 400 | INVALID_ADMIN_*_REQUEST / INVALID_ADMIN_*_QUERY | Body or query failed schema validation; issues[] lists the fields |
| 401 | UNAUTHENTICATED_ACTOR | No resolvable actor identity on the request |
| 403 | TENANT_MISMATCH | x-tenant-id ≠ body/query tenantId |
| 403 | FORBIDDEN (+ permission) | Authenticated, but your enterprise role lacks the required permission |
| 403 | ACTOR_NOT_FOUND | The actor is not a member of the tenant and is not an API-key actor |
| 404 | ORG_NOT_FOUND / MEMBER_NOT_FOUND / CREDENTIAL_NOT_FOUND | The referenced resource does not exist within the tenant |
| 500 | ENTERPRISE_ADMIN_ERROR | Unexpected server error (fail-closed; no partial effect is reported as success) |
Where to start#
Read your trust posture
Call GET /admin/tenant or GET /admin/workspace to get the tenant's environments, trust overview, identity readiness, and your own resolved role and permissions in one response. See Tenant Administration.
Confirm who can do what
Call GET /admin/roles to retrieve the full role/permission matrix plus your effective permissions. See Roles and Token Governance.
Govern credentials and evidence
Issue narrowly-scoped API credentials, and produce signed evidence bundles for auditors. See Roles and Token Governance and Audit Export.
Know your break-glass path
Before an incident, learn the Emergency Controls so you can halt a tenant or environment, pause a connector, or revoke a credential under pressure.