Skip to main content
A delegation lets a machine identity create sessions on behalf of users in an Agent Vault project. If the machine identity sends a user’s email or ID in 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

Set up a delegation

1
In your Agent Vault project, go to Access Control, select the Machine Identities tab, and select the machine identity.
The Access Control page on the Machine Identities tab, listing the github-actions and release-bot machine identities
2
In the Delegation section, select Manage Delegation.
The release-bot machine identity page, with a Delegation section listing the Platform Team group and the users Jordan Lee and Priya Patel, and the Manage Delegation button
3
Expand Not in Delegation, then select Add next to each user or group to add. A group covers every member of the group. If someone isn’t listed, search for them by name. Changes save as you make them.To cover every current and future user in the project instead, turn on All Project Members and select Allow All Members.
The Manage Delegation sheet, with the All Project Members toggle off, a group and two users In Delegation, and the project's other members under Not in Delegation

Remove a user or group from a delegation

1
On the machine identity’s page, select Manage Delegation.
2
Select In Delegation on the user’s or group’s row, then select Remove.
3
Select Remove again to confirm.
If you remove the last user or group, or turn off All Project Members, the machine identity can no longer act on behalf of anyone.

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 in onBehalfOf:
You can also create the session with the Python SDK or the Node.js SDK.
Start the agent with the session token from the response, and revoke the session when the agent finishes.

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 in onBehalfOfUserEmail or onBehalfOfUserId:
The response lists only the access bundles that both the user and the machine identity can use. For each bundle, 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 in onBehalfOfUserEmail or onBehalfOfUserId:
The response lists only the services in an access bundle that both the user and the machine identity can use, which are the services a session on the user’s behalf can use. For each service, 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 in onBehalfOfUserEmail or onBehalfOfUserId:
The response lists only the skills in an access bundle that both the user and the machine identity can use, which are the skills a session on the user’s behalf can use.

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
Each service you list in 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)
To let the machine identity create sessions over one of them, grant the bundle to the machine identity.

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)
If an admin sets up the delegation again, adds the user back to it, or reactivates the user or the machine identity, the session works again. To end a session for good, revoke it. If the user or the machine identity can no longer use the access bundle, the session stops getting credentials for the bundle. The same goes for each service you listed. For a skill you listed, agents that start with the session afterwards don’t get it.

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: On the Sessions page, the Identity column shows the machine identity’s name, followed by “on behalf of” and the user’s name. The session’s details list the user under On Behalf Of.

Audit events

When the machine identity creates the session, Infisical writes an audit event with the machine identity as the actor and the user in onBehalfOfUserId, 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

The machine identity has no delegation. Set one up, or ask an admin of the project to.
The access bundle isn’t granted to the machine identity, or no access bundle has that name. Grant the bundle to the machine identity, or name a bundle the machine identity already has.
The machine identity has no grant on any access bundle in the project. A session on a user’s behalf needs the machine identity to have a grant on at least one access bundle, even if the session sends only inline skills. Grant the machine identity an access bundle.
The delegation doesn’t cover the user, or no active member of your organization has that email or ID. Check the email or ID you sent, then check the users and groups in the machine identity’s delegation.
The access bundle isn’t granted to the user. Grant the bundle to the user, or name a bundle the user already has.
No access bundle granted to the machine identity holds the service, or no service has that name. Grant the machine identity a bundle that holds the service, or use a service from a bundle the machine identity already has.
No access bundle granted to the user holds the service. Grant the user a bundle that holds the service, or use a service from a bundle the user already has.
The user and the machine identity can each use the service, but through different access bundles. A session on the user’s behalf can use a service only if one bundle holds the service and is granted to both of them.To see which services the session can use, list the services on the user’s behalf. To use this service, grant one bundle that holds it to both the user and the machine identity.

Next steps

Create a session

Create a session and start an agent with its token.

HTTP APIs

Leave part of a service’s credential to each member.