onBehalfOf, it creates the session on behalf of that user. Otherwise, it creates the session as itself.
For a session created on behalf of a user, the proxy uses the user’s own personal values, not the machine identity’s. The session can only use the access bundles that both the user and the machine identity have access to.
Use a delegation when one service starts agents for many people, such as a chat bot that runs an agent for each message, or a task runner that runs an agent for each ticket. Each agent then gets no more access than the person who asked for it.
Prerequisites
- The Admin role in the Agent Vault project, or an admin of the project who can set up the delegation for you
- A machine identity that’s a member of the project and can log in with Universal Auth
- A grant for the machine identity on each access bundle its sessions use
- Users who are members of the project and have a grant on the access bundles their agents use
Set up a delegation
- Dashboard
- API



Remove a user or group from a delegation
- Dashboard
- API
Create a session on behalf of a user
Log in as a machine identity, then call the Create session endpoint with the ID of your Agent Vault project (find the project ID), and name the user inonBehalfOf:
- In
onBehalfOf, set eitheruserEmailoruserId, not both - In
accessBundle, name a bundle that both the user and the machine identity can use - In
services, list services from a bundle that both of them can use - In
skills, list skills from a bundle that both of them can use, or send skills with the session ttldefaults to1h, instead of the7ddefault for other sessions
Find the access bundles a session can use
To choose an access bundle for the user, call the List access bundles endpoint as the machine identity with the project’s ID, and name the user inonBehalfOfUserEmail or onBehalfOfUserId:
servicesRequiringSetup lists the services the user hasn’t set up their personal values for yet. The proxy refuses the session’s requests to those services, so add requiresSetup=false to list only the bundles the user has set up.
Find the services a session can use
To choose services for the user, call the List services endpoint as the machine identity with the project’s ID, and name the user inonBehalfOfUserEmail or onBehalfOfUserId:
personalValues shows whether the user has set up their personal values for it. Add requiresSetup=false to list only the services the user has set up.
Find the skills a session can use
To choose skills for the user, call the List skills endpoint as the machine identity with the project’s ID, and name the user inonBehalfOfUserEmail or onBehalfOfUserId:
Access bundles and personal values
A session created on behalf of a user can use an access bundle only if both the user and the machine identity can use the bundle, and the session uses the user’s personal values:- The user can use the access bundles granted to them, directly or through a group (if the user is an admin of the project, every bundle)
- The machine identity can use the access bundles granted to it, directly or through a group (if the machine identity is an admin of the project, every bundle)
- The proxy refuses the session’s requests to a service until the user sets up their personal values for it
services, and each skill you list in skills, also has to be in a bundle that both of them can use, unless both are admins of the project. Skills you send with the session don’t need to be in a bundle.
If a user or group in the delegation can use an access bundle that isn’t granted to the machine identity, Infisical shows the bundle in two places:
- In the machine identity’s Delegation section, the row for the user or group shows the number of excluded bundles, and hovering over the number lists them
- The Get delegation endpoint returns the bundles in
missingAccessBundles(always empty if a machine identity that isn’t an admin of the project reads its own delegation)
Delegation changes
Infisical checks the delegation again each time the proxy polls, once every poll interval (60 seconds by default). The proxy refuses every request on the session if any of these happen:- An admin removes the delegation, or edits it so it no longer covers the user
- The delegation covered the user only through a group, and either the user leaves that group or the group is removed from the project
- The user is removed from the project or from your organization, which also takes the user out of the delegation
- The user or the machine identity is deactivated in your organization
- An admin removes the machine identity from the project, which also deletes its delegation
- Someone deletes the machine identity or the user (the session then shows as Revoked)
Track sessions created on behalf of users
A session created on behalf of a user belongs to the machine identity, so the user can’t see it. Only the machine identity and admins of the project can see the session, read its session logs, and revoke it:- The machine identity, through the Get session, List session logs, and Revoke session endpoints
- Admins, under All Sessions on the Sessions page
Audit events
When the machine identity creates the session, Infisical writes an audit event with the machine identity as the actor and the user inonBehalfOfUserId, onBehalfOfUserName, and onBehalfOfUserEmail. The audit events for changing the session’s label and revoking the session include the same three fields. Infisical also writes an audit event when an admin sets up, changes, or removes a delegation.
Considerations
Machine identity access
A delegation lets a machine identity use other people’s personal values, so protect who can set one and who can use one:- If a machine identity has a delegation, anyone who can log in as the machine identity can send requests with the personal values of every user the delegation covers (protect the machine identity’s credentials as carefully as those users’ own credentials)
- A machine identity with the Admin role in the project can set delegations, including one for itself that covers every member and project admin (give a machine identity the Admin role only if it needs it)
Project membership
- You can add only users and groups that are members of the project
- If a user is in the project only through a group, add the group
- If a user or group leaves the project, Infisical takes them out of the delegation, and adding them back to the project doesn’t add them back to the delegation
Troubleshooting
Creating the session fails with "This machine identity isn't allowed to start sessions on behalf of users"
Creating the session fails with "This machine identity isn't allowed to start sessions on behalf of users"
Creating the session fails with "No access bundle named ... is granted to this machine identity"
Creating the session fails with "No access bundle named ... is granted to this machine identity"
Creating the session fails with "No access bundle in this project is granted to this machine identity"
Creating the session fails with "No access bundle in this project is granted to this machine identity"
Creating the session fails with "This machine identity can't start sessions on behalf of ..."
Creating the session fails with "This machine identity can't start sessions on behalf of ..."
Creating the session fails with "No access bundle named ... is granted to '...'"
Creating the session fails with "No access bundle named ... is granted to '...'"
Creating the session fails with "This machine identity can't use a service called ..."
Creating the session fails with "This machine identity can't use a service called ..."
Creating the session fails with "'...' can't use a service called ..."
Creating the session fails with "'...' can't use a service called ..."
Creating the session fails with "The service ... isn't in an access bundle granted to both this machine identity and '...'"
Creating the session fails with "The service ... isn't in an access bundle granted to both this machine identity and '...'"