Eniyan Docs

Agent RBAC

Named, reusable roles as the governed authority source for your agents. Create a role once, assign it everywhere, edit it live, and route anything outside a role through an approval workflow — with recertification keeping every assignment accountable on a cadence you set.

The authority model

An agent with at least one active role assignment is role-governed. Its permitted scope set becomes:

  • the union of its active roles’ scopes,
  • plus live IdP entitlement delegations (unchanged from the delegation model — an entitlement counts only while the delegator still holds it),
  • plus approved, unexpired scope exceptions,
  • plus the credential’s enrollment-time scopes only if your organization’s manual scopes count policy is on. Off (the default) means roles are definitive: out-of-role authority requires an approved exception.

Three invariants hold everywhere: a role-governed agent is always in declared-scope mode (a role that resolves to zero scopes yields an empty permitted set, never unrestricted legacy behavior); an active JIT task’s required_scopes still takes wholesale precedence; and consumer-delegation and trading-mandate authority domains are untouched — roles govern workforce-agent surfaces only.

Role tiers

  • Organization roles — your org’s shared vocabulary, created by admins or members holding the Role Admin role. Roles marked default are auto-assigned to every agent at onboarding.
  • Operator roles — any member with a linked operator identity can package their own live IdP entitlements into per-purpose roles for the agents they anchor. Scopes are validated as held at creation (SCOPE_NOT_HELD otherwise) and live-filtered at every read: if the creator loses the underlying entitlement or is deactivated, the role’s grant lapses silently — it narrows, never widens.

Roles are live-mutable: edits apply on the next token mint or verification, and every change writes an append-only history entry (who, what scopes added or removed, why). Assignments require a written reason and revoke as a soft delete — the trail survives.

Scope exceptions

When a role-governed agent needs authority outside its roles, request an exception: POST /v1/agent-roles/agents/{agent_id}/exceptions with a scope, a justification, and an optional expiry. Admins and members holding the Agent Approver role decide (POST …/exceptions/{id}/decide; rejection requires a reason the requester sees). Approved exceptions join the permitted set until they expire or are revoked. Every step is audited, and decisions fire the agent.scope_exception_decided webhook.

Recertification

Set a recertification period in the RBAC policy and every role assignment must be re-confirmed on that cadence by an admin or a Role Manager (POST /v1/agent-roles/assignments/{id}/certify, reason required). Two enforcement postures:

  • Advisory (default) — overdue assignments are flagged in the queue and audited; live authority is unaffected.
  • Enforce — overdue assignments go inert: the agent loses those scopes at the next mint or verification (fail closed; the agent stays role-governed) until someone recertifies. The transition audits as agent_role_recert_suspended and fires agent.role_recert_suspended.

Delegated administration

Three org member roles, assignable from Team & Access, spread the work without spreading admin:

  • Role Admin — creates and edits org-level role definitions.
  • Role Manager — assigns and unassigns roles and runs recertification. Admins may restrict a manager to specific operators’ agents (PUT /v1/agent-roles/manager-scopes/{user_id}); an empty restriction set means org-wide.
  • Agent Approver — decides scope-exception requests.

Org admins can do all of the above. An agent’s own operator can always assign existing roles to, and request exceptions for, the agents they anchor.

Org policy

  • Require roles — agents without any role are flagged under advisory scope enforcement or refused (role_required) under block mode, at both verification and the token mint.
  • Single vs multiple roles — restrict agents to exactly one role (assignment of a second returns MULTIPLE_ROLES_NOT_ALLOWED) or allow composition of narrow roles.
  • Manual scopes count — see the authority model above. Off for definitive roles; on for a softer rollout.
  • Recertification period + enforce — see Recertification.

Policy changes are admin-only, audited, and apply at the next mint or verification — the same kill-switch contract as every other governance surface.

Related: Agent Policy (restriction rules that compose on top of role grants), Concepts.