Delegations

The Delegations screen lets you grant a delegation of your rights to an agent, an application or a service, revoke it with all its descendants, manage the mandates that let a scheduled agent act through a service identity, test an authorization through every layer, and revoke at once every delegation rooted at a user. Portal path: /security/delegations, menu Security and governance > Delegations. It is used by users and developers who delegate to an agent, and by security officers and tenant administrators who supervise and revoke.

What the screen shows

The screen (Delegations in portal/src/screens/security-kit.tsx) has four sections.

• Delegations table, read from GET /v1/delegations (cursor paging): columns Delegation, Delegate (for example agent:invoice-assistant), Root principal, Scopes, Depth, Max depth, Status (active, expired, revoked), Expires. Filters Status and Root principal. A click on a row opens the delegation loaded from GET /v1/delegations/{delegation_id}, with the verification of its chain.
• Mandates table, read from GET /v1/mandates (50 rows): columns Mandate, Agent, Service identity, Scopes, Purpose, Status, Approval, Expires. Filter Agent. A click on a row opens the mandate from GET /v1/mandates/{mandate_id}.
• Authorize an action form: "Checks every layer: chain, session, user, agent, delegation, resource and policy."
• Revoke a principal form: "Revokes every delegation rooted at that user."

Form New delegation:

Field	Default	Notes
Delegate		Required, agent:, app:, service: or subagent: followed by a name, for example agent:invoice-assistant.
Scopes		Comma separated, for example rag:query, tools:invoke; never more than you hold.
Audience, Resources		Comma separated lists.
Max classification		public, internal, confidential, restricted, secret; never above your clearance.
Max depth	1	0 to 10.
Redelegation allowed	off	Lets the delegate restrict and pass the delegation on.
Lifetime (seconds)	3600	At least 60, at most the platform limit (delegation_max_ttl_seconds, 86400 by default).
Purpose		Free text.

Form New mandate: Agent (required), Service identity (required), Purpose (required, 3 characters at least), Scopes, Audience, Resources, Max classification, Max depth (0), TTL (days) (30, at most mandate_max_ttl_days, 365 by default), Schedule.

Actions

Button or action	What it does	API call	Roles
New delegation (then Create)	Creates a root delegation from you to the delegate; scopes and classification are capped by yours.	POST /v1/delegations	Every user of the tenant (an agent cannot create a root delegation)
Revoke (row menu of an active delegation)	Opens a form with Reason (required), then Revoke: the delegation, every descendant and their execution contexts are revoked.	POST /v1/delegations/{delegation_id}/revoke	Root principal, creator or on behalf of; tenant_admin, security_officer for any
Row click (Delegations)	Opens the delegation with its chain.	GET /v1/delegations/{delegation_id}	Parties of the delegation; tenant_admin, security_officer, auditor, agent
New mandate (then Create)	Requests a mandate; it waits for an approval decided by another person.	POST /v1/mandates	tenant_admin, developer, security_officer (button hidden for others)
Revoke (row menu of an approved or pending mandate)	Opens a form with Reason (required), then Revoke.	POST /v1/mandates/{mandate_id}/revoke	Requester; tenant_admin, security_officer for any
Row click (Mandates)	Opens the mandate.	GET /v1/mandates/{mandate_id}	Every user of the tenant
Run (Authorize an action)	Checks an Action (required, for example tool.invoke) for a Delegation or a Run id, with optional Scope, Resource (tool:crm.lookup), Relation, Data classification; shows the decision.	POST /v1/delegations/authorize	Every user of the tenant
Run (Revoke a principal)	After a confirmation, revokes every delegation rooted at Principal, with a Reason (both required).	POST /v1/delegations/revoke-principal	tenant_admin, security_officer (form hidden for others)
Filter, refresh icon	Applies the filters, reads a list again.	GET /v1/delegations or GET /v1/mandates	Every user of the tenant

Roles

The portal hides New mandate from roles other than tenant_admin, developer, security_officer, and the Revoke a principal form from roles other than ROLES.delegationAdmins (tenant_admin, security_officer, portal/src/lib/kit.ts). The Control Plane (services/control-plane/src/eai/domains/delegation/routes.py, services/control-plane/src/eai/domains/delegation/service.py, services/control-plane/src/eai/domains/delegation/mandates.py) decides the rest:

• everyone in the tenant can delegate their own rights, never more than they hold;
• tenant_admin, security_officer and auditor see every delegation; other users see only those they root, created or act on behalf of;
• a mandate is approved by another person than its requester, through the approvals inbox;
• platform_admin passes every role check.

Typical tasks

Delegate a read access to an agent

1. Open the form. A delegation lets the agent act for you within limits. Click New delegation. Expected result: a side panel with Max depth 1 and Lifetime (seconds) 3600. If it fails: no table means the list did not load; click Retry.
2. Set the limits. Enter Delegate agent:<name>, Scopes rag:query, Max classification internal, keep Redelegation allowed off. Expected result: the form is complete. If it fails: nothing to retry at this step.
3. Create. Click Create. Expected result: the message Created and a row active with its expiry. If it fails: delegation_scope_exceeds (HTTP 403) or delegation_classification_exceeds (HTTP 403) when you ask more than you hold; delegation_ttl_exceeded (HTTP 400) above the platform limit; invalid_request (HTTP 400) for a delegate without a known prefix.
4. Test it. Form Authorize an action: Action rag.query, Delegation the new identifier, then Run. Expected result: the decision of every layer. If it fails: invalid_request with "delegation_id or run_id is required" when both are empty.

Offboard a user

1. Find their delegations. Filter Root principal with the user id, Filter. Expected result: every delegation rooted at that user. If it fails: an empty table when you are not an administrator and the delegations are not yours.
2. Revoke everything. Form Revoke a principal: Principal the user id, Reason, Run, accept the confirmation. Expected result: the result lists the revoked delegations; their rows turn revoked after a refresh. If it fails: forbidden (HTTP 403) when you are neither tenant_admin nor security_officer.

Give a scheduled agent a mandate

1. Request it. A scheduled agent has no user behind it: the mandate binds it to a service identity. Click New mandate, fill Agent, Service identity, Purpose, Scopes, TTL (days), then Create. Expected result: a row pending with its Approval. If it fails: service_identity_not_found (HTTP 404), service_identity_disabled (HTTP 409), delegation_scope_exceeds (HTTP 403) when the scopes exceed those of the identity, mandate_ttl_exceeded (HTTP 400).
2. Have it approved. Another person decides the approval in the approvals inbox. Expected result: the status approved. If it fails: the requester cannot decide its own approval.

Troubleshooting

Symptom	Cause	Fix
delegation_root_forbidden (HTTP 403)	An agent cannot create a root delegation: it can only restrict the one it received.	Create the delegation from a user or an application.
delegation_scope_exceeds (HTTP 403)	The requested rights exceed the rights held by the delegator.	Reduce Scopes.
delegation_classification_exceeds (HTTP 403)	The requested classification exceeds the clearance of the delegator.	Lower Max classification.
delegation_ttl_exceeded (HTTP 400)	The lifetime exceeds the maximum of the platform.	Lower Lifetime (seconds).
invalid_request (HTTP 400) with max_depth	Max depth above 10.	Choose a value from 0 to 10.
forbidden (HTTP 403) on Revoke	You are not a party of the delegation and not an administrator.	Ask a tenant_admin or a security_officer.
delegation_not_found (HTTP 404)	Unknown delegation, or one you cannot see.	Check the identifier and your roles.
mandate_closed (HTTP 409)	The mandate is already rejected or revoked.	Request a new mandate.
validation_error (HTTP 422) on Authorize an action	Action must look like tool.invoke, Resource like tool:crm.lookup.	Fix the format.

Related pages

• Break glass
• Permissions (ReBAC)
• Service identities
• Approvals
• Agent schedules
• Identity, context, delegation
• Execution context guide