Create Agent Vault sessions with the API

Create a session for each agent run from your own code, using a machine identity instead of the Infisical dashboard.

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 in the same project as the access bundle, which the agent’s machine can reach
• The Admin role in the Agent Vault project, or a project 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.

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

2. 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.

3. 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.

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

​

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 ID of your Agent Vault project, the name of the access bundle, how long the session should last, and optionally a label that says what the session is for. To get the ID, see Find the project ID.

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

• projectId is the ID of the Agent Vault project that the access bundle is in
• accessBundle is the name of the access bundle the session carries (an admin can leave it out and send inline services instead)
• 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)
• label is optional and describes what the session is for, in up to 128 characters (see Label a session)

If your code runs agents for other people, as a chat bot does, the machine identity can create each session on behalf of the person who asked, so the session uses that person’s personal values and gets no more access than that person.

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

{
  "session": {
    "id": "6f1c2a9e-3b7d-4e8a-9c41-2d5f7b8e0a13",
    "projectId": "<project-id>",
    "label": "nightly deploy",
    "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

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.

Without the CLI

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 your Agent Vault project, go to Sessions and select All Sessions. Find the session you created by its label in the Label column, or search for the label. The session’s Status is Active while the agent runs, and Revoked after Step 5.

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, the name in accessBundle is wrong, or projectId names a different project than the one the access bundle is in. Check the name on the project’s 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.

​

Next steps

Your own agent

Send your agent’s requests through the proxy from your own code.

Session logs

Record every request an agent makes during a session.