Sessions on behalf of users

Let a machine identity, such as a chat bot or a task runner, create sessions on behalf of users, so each session uses the personal values of the user it’s for.

A delegation lets a machine identity create sessions on behalf of users in an Agent Vault project. The machine identity can still create sessions as itself. It creates a session on behalf of a user only if it sends the user’s email or ID in onBehalfOf. 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 use an access bundle only if both the user and the machine identity can use the bundle.

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, as Step 1 of Create sessions with the API describes
• 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

1. In your Agent Vault project, go to Access Control, select the Machine Identities tab, and select the machine identity.

   
2. In the Delegation section, select Manage Delegation.

   
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.

   

API

Call the endpoint that sets a delegation with the machine identity’s ID and your project’s ID:

curl -X PUT "https://app.infisical.com/api/v1/agent-vault/delegations/<machine-identity-id>?projectId=<project-id>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"scope": "selected", "groupIds": ["<group-id>"]}'

Set scope to all-members to cover every member of the project, or to selected with userIds, groupIds, or both. The request replaces any delegation the machine identity already has.

To add or remove users and groups without sending the whole list, call the endpoint that adds users and groups or the endpoint that removes them.

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.

To take a user or group out of the delegation, select Manage Delegation, select In Delegation on its row, select Remove, then 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.

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 you’d protect 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, project admins included. Give a machine identity the Admin role only if it needs it

​

Create a session on behalf of a user

Log in as the machine identity, as Step 2 of Create sessions with the API describes. Then call the endpoint that creates a session with the ID of your Agent Vault project (find the project ID), and name the user in onBehalfOf:

curl -X POST https://app.infisical.com/api/v1/agent-vault/sessions \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "<project-id>", "accessBundle": "<access-bundle-name>", "onBehalfOf": {"userEmail": "<user-email>"}, "ttl": "15m"}'

• In onBehalfOf, set either userEmail or userId, not both
• In accessBundle, name a bundle that both the user and the machine identity can use
• ttl defaults to 1h, instead of the 7d default for other sessions

Start the agent with the session token from the response, and revoke the session when the agent finishes, as Step 4 of Create sessions with the API describes.

You can also create the session with the Python SDK or the Node.js SDK.

​

Find the access bundles a session can use

To choose an access bundle for the user, call the endpoint that lists access bundles as the machine identity with the project’s ID, and name the user in onBehalfOfUserEmail or onBehalfOfUserId:

curl "https://app.infisical.com/api/v1/agent-vault/access-bundles?projectId=<project-id>&onBehalfOfUserEmail=<user-email>" \
  -H "Authorization: Bearer <access-token>"

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.

​

What the session can reach

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

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 endpoint that reads a delegation 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.

​

When the session stops working

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, as Access changes describes.

​

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 endpoints that read a session, list its session logs, and revoke a session
• Admins, under All Sessions on the Sessions page

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.

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.

​

Troubleshooting

Creating the session fails with "This machine identity isn't allowed to start sessions on behalf of users"

The machine identity has no delegation. Set one up, or ask an admin of the project to.

Creating the session fails with "No access bundle named ... is granted to this machine identity"

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.

Creating the session fails with "This machine identity can't start sessions on behalf of ..."

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.

Creating the session fails with "No access bundle named ... is granted to '...'"

The access bundle isn’t granted to the user. Grant the bundle to the user, or name a bundle the user already has.

​

Next steps

Create sessions with the API

Create, use, and revoke a session from your own code.

HTTP APIs

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