Agent Delegation
Agent delegation lets a user give an agent they own, or created, a bounded and time-limited subset of their own Hub access. For example, an agent might read agents in other projects the user can see, or message them. The user issues a grant. The agent exchanges the grant, with its own agent token, for a short-lived delegated credential and uses that credential on the Hub.
Every use is checked again against the issuer’s live access at that moment. If the issuer loses access, is suspended or deleted, or stops controlling the agent, or the grant is revoked or expires, the agent’s delegated access stops.
What a delegated decision bounds, and what it does not
Section titled “What a delegated decision bounds, and what it does not”The grant bounds each authorization decision, not the computation that follows it. Each delegated request is allowed only for what the issuer may do right now on that target, reduced by:
- the grant’s frozen permission ceiling;
- its boundary (one project, or the Hub);
- the Hub delegation policy;
- access constraints.
What happens after an allowed decision is not bounded by the grant:
agent:messageinstructs an independently authorized recipient. The recipient acts with its own authority, and what it does next is not bounded by the messaging grant. Messages show the agent as the sender and the issuer as the authorizer.agent:attachgives shell access in the target agent’s container. Before you delegate it, know what that includes:- No in-container client: the Hub authorizes a delegated attach, but a delegated attach is
not supported through the sciontool delegation socket. The socket forwards plain HTTP
requests only, not the WebSocket upgrade that attach needs, and the scion CLI does not use
delegated credentials. Tracked in ptone/scion#7473. The points below describe what the Hub
admits for a delegated credential that holds
agent:attach. - The target’s credentials and material:
- its agent token (
~/.scion/scion-token, valid for 10 hours and refreshable); - its environment and files;
- its own sciontool delegation socket, together with any delegated credentials that sciontool holds.
- its agent token (
- The target’s downstream authority: the attaching party can act with it, and the grant does not bound it.
- Sessions: an established session can outlive revocation and the credential’s expiry. Revoking cannot retract material already copied.
- When it is checked: attach is authorized only at the WebSocket handshake and at reconnect.
- Broker path only: a delegated attach uses only the Runtime Broker’s terminal path. An agent
whose attach would take the conduit path (for example, on a managed runtime) is refused with
503 runtime_attach_unsupported.
- No in-container client: the Hub authorizes a delegated attach, but a delegated attach is
not supported through the sciontool delegation socket. The socket forwards plain HTTP
requests only, not the WebSocket upgrade that attach needs, and the scion CLI does not use
delegated credentials. Tracked in ptone/scion#7473. The points below describe what the Hub
admits for a delegated credential that holds
scion hub delegation create --help repeats the attach consequences, and the command prints them
whenever agent:attach is selected.
The experiment flag
Section titled “The experiment flag”hub.agent_delegation gates exactly three things:
- the issuance and exchange routes, which answer
404while it is off; - the authentication arm for delegated credentials (
scion_adt_…), which refuses every delegated credential while it is off; - the delegated decision procedure, which checks it again.
Grant management stays available while the experiment is off. Grant list, read, revoke, credential revoke and revoke-all always answer, so you can review and end grants during a disabled period.
Turning the experiment off suspends grants; it does not revoke them. Stored grants and unexpired credentials work again when it is turned back on. To end grants for good, revoke them, or use revoke-all.
An optional operational setting, agent_delegation_policy, can narrow the delegable permissions
per boundary kind. It can never widen them. See Server configuration.
Issuance
Section titled “Issuance”scion hub delegation create <agent> --permission agent:read --permission agent:list --boundary hub --name nightly-triage --expires 7d- Who may issue: the agent’s owner, or a user in its recorded ancestry, who is admitted to the agent’s project. Issuance needs an interactive session; an access token, an agent token, a delegated credential or a dev session is refused.
- What may be delegated: exact read and list permissions,
agent:messageandagent:attach, each only where the issuer could select it for the chosen boundary. A delegatedagent:attachis not supported through the sciontool delegation socket (see above). Creating agents, starting, stopping and deleting them, and every credential operation are not delegable. - Lifetimes: a grant lasts 7 days by default, at most 30. Each delegated credential lasts 15 minutes by default, at most 60, and never outlives the grant or the agent token used for the exchange.
- Limits: at most 2 active credentials per grant, 10 active grants per agent and 50 per issuer. There is no subdelegation.
- Name, purpose and labels are descriptive, user-supplied text. They never confer identity.
Exchange
Section titled “Exchange”The agent exchanges a grant through sciontool, with its own agent token:
POST /api/v1/agents/{agentId}/delegations/{grantId}/exchange. sciontool keeps the delegated
credential in memory only, and re-exchanges before it expires and after every agent token refresh.
Processes in the agent container send plain HTTP requests to a local socket (mode 0600), naming
the grant in the X-Scion-Delegation-Grant header. sciontool forwards each request to the Hub with
the delegated credential attached, and never returns the credential to the process, writes it to a
file or puts it in a child process’s environment. The scion CLI never consumes a delegated
credential.
A refresh of the agent’s own token ends the credentials exchanged with the old token at their next use. sciontool then exchanges again with the new token.
Transport authentication in front of the Hub
Section titled “Transport authentication in front of the Hub”sciontool sends delegated requests with Authorization: Bearer scion_adt_…. In the default
transport header mode, SCION_TRANSPORT_MODE unset (HeaderAuthorization), the transport OIDC token
is added only when a request has no Authorization header. A delegated request from sciontool
therefore goes out without the transport OIDC token.
What to configure:
- The Hub sits behind Google IAP or Cloud Run invoker IAM: set the agents’
SCION_TRANSPORT_MODEtoiaporcloudrun_invoker. The transport token then travels inProxy-AuthorizationorX-Serverless-Authorization, beside the delegated credential, and delegated requests pass the proxy. - No platform proxy requires a transport credential: nothing is needed.
Delegated lists
Section titled “Delegated lists”A delegated credential can use four list routes. Each needs its list permission, and each listed item is also checked for its read permission:
| Route | List permission | Each item needs |
|---|---|---|
GET /api/v1/agents |
agent:list |
agent:read |
GET /api/v1/projects/{id}/agents |
agent:list |
agent:read |
GET /api/v1/skills |
skill:list |
skill:read |
GET /api/v1/templates |
template:list |
template:read |
skill:read and template:read only decide which skills and templates a list returns. A
delegated credential cannot read a single skill or template, download one, or resolve a skill:
those routes answer 403 credential_not_admitted.
- Scope: the issuer’s own list access right now, within the grant’s boundary. A
project-bounded grant lists only that project. The project agent list lists only its one
project, and lists nothing for a project outside the issuer’s access or the grant’s boundary.
A project that does not exist answers
404, as it does for every caller; name the project by its ID, because a slug in the path answers403 credential_not_admitted. The agent’s own access adds nothing. - Project items only on the skill and template lists: only project-scoped skills and templates
are listed. Global (hub catalog) and user-scoped skills and templates are never listed
to a delegated credential.
scope=globalandscope=userlist nothing, and so does aprojectIdorscopeIdoutside the scope. The retiredscope=coreanswers400on the skill list, for a delegated credential as for every other caller. - A refused list is empty, not an error: when the list itself is refused (the grant lacks the
list permission, the issuer has no list access, any revocation-chain check fails, or the Hub
hits an error deciding the scope), the answer is
200with an empty list andtotalCount: 0. The reason is never in the response. - Each item is checked too: an item is listed only if the issuer may also read it, so the grant
needs the read permission as well. A grant with the list permission but not the read permission
lists nothing. Each listed item carries only the
readcapability, an agent’s environment is redacted, and the list has no list-level capabilities. - Order and filters: the default order only. On the agent lists,
sortoridsanswers400 delegated_list_sort_unsupported, and on the hub agent listscope=mine,scope=sharedandmine=truelist nothing, because the agent owns no projects.limitis 1 to 100, 50 by default. - Paging:
- A page can be empty and still carry a
nextCursor, andtotalCountcan be a lower bound (totalCountApproximate: true). FollownextCursoruntil it is absent. - Cursors are opaque: pass them back unchanged.
- A cursor works only for the delegated credential that received it, so a credential from a new exchange cannot resume a walk that an earlier credential started.
400 invalid_cursormeans “restart from the first page”.
- A page can be empty and still carry a
- Audit: the decision log does not include list decisions for a delegated credential, and the in-memory summary of a list’s per-item decisions (counts and up to 50 refused item IDs) is not written to the decision log.
Revoke, revoke-all and lists
Section titled “Revoke, revoke-all and lists”| Command | Route | Who may act |
|---|---|---|
scion hub delegation list [<agent>] |
GET /api/v1/agents/{agentId}/delegations, GET /api/v1/users/me/delegations |
per grant, as for revoke; grants outside your authority are left out |
scion hub delegation get <agent> <grant> |
GET /api/v1/agents/{agentId}/delegations/{grantId} |
as for list; a grant outside your authority answers 404 grant_not_found |
scion hub delegation revoke <agent> <grant> |
DELETE /api/v1/agents/{agentId}/delegations/{grantId} |
the issuer; the bound agent (it relinquishes its own grant); the agent’s current owner; hub admins, for any grant; project owners and admins of P, for grants bounded to project P only |
scion hub delegation revoke <agent> <grant> --credential <id> |
DELETE …/delegations/{grantId}/credentials/{credentialId} |
as for revoke |
scion hub delegation revoke-all --mine |
POST /api/v1/users/me/delegations/revoke-all |
your own issued grants |
scion hub delegation revoke-all <agent> |
POST /api/v1/agents/{agentId}/delegations/revoke-all |
per grant: the issuer and the agent’s current owner, and holders of agent.delegation.revoke_all (hub admins, for any grant) |
- Names: the revoke-all permission is
agent.delegation.revoke_all. Its catalog operation isagent.delegation.revokeall, because operation IDs take no underscore. - A hub-bounded grant is out of reach for project admins, whichever project the agent lives in.
- Revoke ends the grant and every credential exchanged from it, in one transaction with its
audit record. Revoking an already revoked grant answers
204and records nothing new. - Revoke-all revokes every unrevoked grant it covers, expired ones included, in one transaction.
- A failure revokes nothing.
- Grants you may see but not revoke this way are reported as
skipped, with the reasonforbidden. Revoke those one by one. For example, a project admin’s per-agent revoke-all skips project-bounded grants, because project roles holdagent.delegation.revokebut notagent.delegation.revoke_all. - Revoke-all needs a session; the bound agent relinquishes its grants one by one.
- The CLI asks for confirmation on a terminal (default No).
--yes(-y) or--non-interactiveconfirms; without a terminal and without either flag it refuses.
- Management needs a session (or, on the per-agent routes other than revoke-all, the bound agent’s own agent token). Delegated credentials and access tokens are refused.
- Responses never carry a credential, its hash or any prefix beyond
scion_adt_. - Lists are not paginated.
- Revoked and expired grants stay listed. They are never purged. Credential rows are deleted 24 hours after they expire.
- Lifecycle changes revoke grants automatically:
- Transactional: deleting, restoring or reincarnating an agent, and deleting its project.
- Best effort: suspending the agent (both manual suspension and idle auto-suspension, before releasing its start claim), and suspending or deleting the issuer. If the agent is resumed before a suspend’s revocation runs, the grants issued to the resumed run are kept.
- Unsuspending an issuer makes their unrevoked, unexpired grants work again, as for access tokens. To end grants, use revoke-all.
Dual audit
Section titled “Dual audit”-
Mutation records (always written). Every issuance, exchange and revocation (single, credential, revoke-all, and lifecycle) writes a mutation audit record. Each record carries:
- the actor agent;
- the authorizing user (the issuer);
- the grant;
- the exchange agent credential, where one applies.
Each revoke-all revocation writes its own
agent_delegation_grant_revokerecord. -
Delegated messages. A message sent with a delegated credential is attributed on the message record itself: the sender is the actor agent, and the message carries the authorizing user and the grant. A message send writes no mutation audit record.
-
Decision records. The decision log does not include decisions for a delegated credential, allow or deny. Tracked in ptone/scion#2132.
Responses to a denied delegated request carry no decision reason.