Sessions on behalf of users

​

Prerequisites

• The Admin role in Agent Vault, or an Agent Vault admin who can set up the delegation for you
• A machine identity that’s a member of Agent Vault 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 Agent Vault and have a grant on the access bundles their agents use

​

Set up a delegation

• Dashboard
• API

1

In Agent Vault, 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 Agent Vault instead, turn on All Agent Vault Members and select Allow All Members.

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

curl -X PUT https://app.infisical.com/api/v1/agent-vault/delegations/<machine-identity-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 Agent Vault member, 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.

​

Create a session on behalf of a user

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

• In onBehalfOf, set either userEmail or userId, not both
• In accessBundles, 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

​

Find the access bundles a session can use

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

​

What the session can reach

• The user can use the access bundles granted to them, directly or through a group (if the user is an Agent Vault admin, every bundle)
• The machine identity can use the access bundles granted to it, directly or through a group (if the machine identity is an Agent Vault admin, every bundle)
• The proxy refuses the session’s requests to a service until the user sets up their personal values for it

• 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 Agent Vault admin reads its own delegation)

​

When the session stops working

• 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 Agent Vault
• The user is removed from Agent Vault 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 Agent Vault, 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

• 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

​

Troubleshooting

​

Next steps