Roles and Token Governance#

This page covers the two governance levers a tenant administrator controls: who can do what (the enterprise role/permission matrix) and which machine credentials exist (the API credential lifecycle). Both are tenant-scoped, permission-checked, and audited.

The role/permission matrix#

There are six enterprise roles. Each resolves to a fixed set of the eleven enterprise permissions. admin is currently equivalent to owner.

What each role is for:

• owner / admin — full tenant control, including member management, identity settings, and emergency actions.
• operator — hands-on runtime operator: policies, gateway, approvals, and credential governance, but no member, identity, or emergency authority.
• auditor — read everything and export evidence, with no mutating authority.
• reviewer — approval-focused, with read-only trust context.
• read_only — trust and audit visibility only.

API credentials#

Credentials are the intended_live_ API keys your services use to call the runtime (a legacy mrt_ prefix is still accepted on older keys). They are issued, listed, and revoked through /admin/api-tokens, and every lifecycle action is recorded as an event.

List credentials#

Each credential record exposes: id, name, prefix (the first 12 characters of the key, e.g. intended_liv...), environmentKey, scopes[], status (active · revoked · expired), createdBy, createdAt, lastUsedAt, revokedAt, and eventCount. The raw key value is never returned here — only on creation.

Create a credential#

curl -X POST https://api.intended.so/admin/api-tokens \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "tenant_acme_prod",
    "name": "ci-pipeline",
    "environmentKey": "production",
    "scopes": ["intent:create", "authority:policy:read"],
    "ipAllowlist": ["203.0.113.10"]
  }'
# 201 → { "credential": { "id": "...", "prefix": "intended_liv...", ... }, "secret": "intended_live_<64 hex>" }

Revoke a credential#

curl -X POST https://api.intended.so/admin/api-tokens/cred_123/revoke \
  -H "Authorization: Bearer $INTENDED_API_KEY" \
  -H "x-tenant-id: tenant_acme_prod" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "tenant_acme_prod", "reason": "Offboarding ci-pipeline" }'

The credential event ledger#

Every create and revoke writes an apiCredentialEvent (eventType: created · revoked · rotated · used) with the acting actorId, environmentKey, a human-readable summary, and createdAt. These events are returned in the events[] array of GET /admin/api-tokens (most recent first) and feed the audit evidence export. They give you a complete, queryable history of credential governance for a tenant.

Failure modes#

Next Steps#

• API Authentication — how keys and scopes are checked at the gate
• Audit Export
• Emergency Controls