Create Agent Vault sessions with the API

You can use the Infisical API to create a new session every time your agent starts. Your code authenticates as a machine identity, creates a session with an access bundle, passes the session token to the agent, and revokes the session when the agent finishes. This is useful if your code starts your agents or creates sessions for agents on other machines, such as a job runner, an orchestrator, or a backend that runs an agent for each task.

If a shell command starts the agent on the machine where it runs, such as a cron job or a container entrypoint, the Infisical CLI can create and revoke each session for you without any code.

Prerequisites

An access bundle with a service for each API the agent calls
A running proxy that the agent’s machine can reach
The Admin role in Agent Vault, or an Agent Vault admin who can complete Step 1 for you

Step 1: Set up a machine identity

Your code creates sessions as a machine identity, so that sessions don’t depend on a person’s account.

In Agent Vault, go to Access Control > Machine Identities and select Add Machine Identity.

On the Create New tab, enter a Name, choose Member in Role, then select Create. Infisical creates the machine identity with Universal Auth and opens its page.

To use a machine identity that already exists in your organization, select the Assign Existing tab instead.

On the machine identity’s page, select Universal Auth under Authentication. Copy the Client ID, then select Add Client Secret and copy the client secret.

Go to Access Bundles and open the access bundle the agent uses. Select Options > Manage Access, then select Grant Access. Select the machine identity, then select Grant Access.

Step 2: Log in as the machine identity

Call the login endpoint for Universal Auth with the client ID and client secret:

curl -X POST https://app.infisical.com/api/v1/auth/universal-auth/login \
  -H "Content-Type: application/json" \
  -d '{"clientId": "<client-id>", "clientSecret": "<client-secret>"}'

If you self-host Infisical, replace https://app.infisical.com with the address of your instance, here and in every later request. The response includes an accessToken, which you send with each request in the next steps, and expiresIn, the number of seconds until the access token expires. Log in again when the access token expires.

If your code runs on a cloud provider or in Kubernetes, you can use another authentication method, such as AWS Auth or Kubernetes Auth, so that your code doesn’t need a client secret. Each method returns an access token that works the same way in the next steps.

Step 3: Create a session

Call the endpoint that creates a session with the name of the access bundle and how long the session should last:

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>"], "ttl": "1h"}'

accessBundles takes a list, but a session can have only one access bundle, so the list must have exactly one name
ttl accepts a duration of at least one minute, such as 30m, 8h, or 7d, or never, and defaults to 7d (see Choose how long a session lasts to pick a value)

The response includes the session’s ID, the session token, and when the session expires:

{
  "session": {
    "id": "6f1c2a9e-3b7d-4e8a-9c41-2d5f7b8e0a13",
    "token": "<session-token>",
    "expiresAt": "2026-10-07T19:00:00.000Z"
  }
}

Save the ID, which you need to revoke the session in Step 5. You can’t retrieve the session token again after this response.

Choose how long a session lasts

Pick the ttl based on how long your agents run:

How your agents run	What to do
A job that finishes, such as a task from a queue or a scheduled run	Create a session for each job, with a `ttl` a little longer than the longest job, and revoke the session when the job ends
A process that keeps running, such as a service or a chat bot	Create a session with a `ttl` such as `24h`. Before the session expires, create a new session, switch the agent to the new token, then revoke the old session

Step 4: Start the agent with the session token

The agent uses the session token to authenticate to the proxy. How you pass the token to the agent depends on how you start the agent:

With the CLI
Without the CLI

Start the agent with infisical agent-vault run, and pass the session token and the proxy’s address:

infisical agent-vault run \
  --session-token <session-token> \
  --proxy <proxy-host>:17323 \
  -- <agent-command>

The CLI trusts the proxy’s certificate for the agent and sends the agent’s requests through the proxy.

Set these environment variables for the agent’s process, and point its certificate variables at the proxy’s certificate, as Connect your own agent describes:

export HTTPS_PROXY=http://x-agent-vault:<session-token>@<proxy-host>:17323
export HTTP_PROXY=http://x-agent-vault:<session-token>@<proxy-host>:17323

If you built the agent yourself, you can instead set the proxy in the agent’s HTTP client. Connect your own agent has examples for Python, Node.js, and Go.

Step 5: Revoke the session

When the agent finishes, call the endpoint that revokes a session with the session’s ID:

curl -X POST https://app.infisical.com/api/v1/agent-vault/sessions/<session-id>/revoke \
  -H "Authorization: Bearer <access-token>"

The proxy stops attaching credentials for the session within one poll interval. Revoke the session even if the agent fails, for example in a finally block or an exit handler. If your code exits before it can revoke the session, the session stops working when its ttl runs out.

Step 6: Verify it works

In Agent Vault, go to Sessions and select All Sessions. The Identity column shows the machine identity’s name for the session you created. The session’s Status is Active while the agent runs, and Revoked after Step 5. If you’ve set up session logs, view the session’s logs to check which requests the agent made during the session.

Your code now creates a session for each agent run, and the agent’s credentials stop working when you revoke the session or its ttl runs out.

Troubleshooting

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

The machine identity doesn’t have a grant on the access bundle, or the name in accessBundles is wrong. Check the name on the Access Bundles page, and grant the bundle to the machine identity.

Creating or revoking a session fails with 401 after your code has run for a while

The machine identity’s access token expired. Log in again to get a new access token. Sessions you already created keep working, because a session doesn’t depend on the access token that created it.

Get started

Agent guides

Concepts

Create Agent Vault sessions with the API

Prerequisites

Step 1: Set up a machine identity

Step 2: Log in as the machine identity

Step 3: Create a session

Choose how long a session lasts

Step 4: Start the agent with the session token

Step 5: Revoke the session

Step 6: Verify it works

Troubleshooting

Next steps

Your own agent

Session logs

​Prerequisites

​Step 1: Set up a machine identity

​Step 2: Log in as the machine identity

​Step 3: Create a session

​Choose how long a session lasts

​Step 4: Start the agent with the session token

​Step 5: Revoke the session

​Step 6: Verify it works

​Troubleshooting

​Next steps

Your own agent

Session logs

Prerequisites

Step 1: Set up a machine identity

Step 2: Log in as the machine identity

Step 3: Create a session

Choose how long a session lasts

Step 4: Start the agent with the session token

Step 5: Revoke the session

Step 6: Verify it works

Troubleshooting

Next steps