Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
---
title: "Sessions"
description: "Time-bound grants that let AI agents access services without holding real credentials."
---
A session is a time-bound grant scoped to one [access bundle](/documentation/platform/agent-vault/access-bundles), to [inline services](/documentation/platform/agent-vault/inline-services) that an admin sends with the session, or to both. Infisical returns a session token that identifies the session, and the agent uses that token to authenticate to the [proxy](/documentation/platform/agent-vault/proxies) on every outbound request. The proxy then attaches the real credential from the matching [service](/documentation/platform/agent-vault/services) at the network boundary.
Every session expires on a schedule you set. When the session expires (or [you revoke it](#revoke-a-session)), the proxy stops attaching credentials to the agent's requests within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).
## Create a session
Anyone granted at least one access bundle can create a session. Admins can create one with any access bundle.
<Tip>
If you want to create sessions programmatically, you can have a [machine identity](/documentation/platform/identities/machine-identities) create a new session for each run using [the CLI](/documentation/platform/agent-vault/sessions-cli), [the API](/documentation/platform/agent-vault/sessions-api), or [the Python SDK](/sdks/languages/python#agent_vault-sessions). A machine identity can also create sessions [on behalf of users](/documentation/platform/agent-vault/sessions-on-behalf-of-users), so that each agent uses the personal values of the person it runs for and gets no more access than that person.
</Tip>
<Tabs>
<Tab title="Dashboard">
<Steps>
<Step>
In Agent Vault, go to **Sessions** and select **Create Session**.
</Step>
<Step>
Pick the **Access Bundle** the agent should use, optionally enter a **Label** that says what the session is for, set a duration under **Expires**, then select **Create Session**.
<Frame>
<img src="/images/platform/agent-vault/session-create.png" alt="The Create Session dialog with an access bundle picked, a label, and a seven day expiry" />
</Frame>
</Step>
<Step>
Copy the command shown. The session token appears once and can't be retrieved again.
<Frame>
<img src="/images/platform/agent-vault/session-created.png" alt="The Session Created dialog showing the run command with the session token shown once" />
</Frame>
</Step>
</Steps>
Hand the copied command to whoever will start the agent. No Infisical login is needed on that machine.
You can also pass the token in the environment instead:
```bash
export INFISICAL_AGENT_VAULT_SESSION_TOKEN=<session-token>
infisical agent-vault run --proxy <proxy-address> -- claude
```
</Tab>
<Tab title="CLI">
`infisical agent-vault run` creates a session for you when you name the access bundle:
```bash
infisical agent-vault run --access-bundle <bundle-name> --proxy <proxy-address> -- <agent-command>
```
Set the duration with [`--ttl`](/cli/reference#agent-vault-run--flag-ttl), which takes a value like `30m`, `8h`, `7d`, or `never`. To [label the session](#label-a-session), pass [`--label`](/cli/reference#agent-vault-run--flag-label).
The CLI creates the session as your user by default, or as a machine identity when you pass `--client-id` and `--client-secret` (or their environment variables). It revokes the session when the agent exits unless you pass `--keep-session`.
</Tab>
<Tab title="API">
Call [the endpoint that creates a session](/api-reference/endpoints/agent-vault-sessions/create) with the access bundle's name, a `ttl`, and optionally a `label`:
```bash
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", "label": "nightly deploy"}'
```
The response includes the session token.
</Tab>
</Tabs>
<Tip>
Picking **Never** as the duration keeps the session working until someone revokes it. Only use this for long-running agents, and revoke the session once the agent has finished.
</Tip>
## Label a session
A label is a short description of what a session is for, such as `nightly deploy` or `support ticket triage`. If one identity creates many sessions, the label is how you tell the sessions apart on the **Sessions** page, and you can search sessions by their label. A label can be up to 128 characters, and can't contain line breaks, tabs, or invisible characters such as zero-width spaces.
You can add, change, or remove a session's label, even after the session expires or is revoked:
- In Agent Vault, go to **Sessions**, open the session's menu, and select **Add Label** or **Edit Label**
- From an agent or a script, call [the endpoint that updates a session](/api-reference/endpoints/agent-vault-sessions/update), for example to record what the agent is working on
## View session logs
[Session logs](/documentation/platform/agent-vault/session-logs) record every request an agent makes during a session. To view them, go to **Sessions** and select **View Session Logs** on the session's row. You can filter and search the requests, and while the session is active, new logs keep appearing.
<Frame>
<img src="/images/platform/agent-vault/session-logs-view.png" alt="The Session Logs sheet for an active session, listing each request's time, method, host, path, upstream status, and outcome" />
</Frame>
## Revoke a session
To revoke a session before it expires, go to the **Sessions** page, open the session's menu, and select **Revoke Session**. The proxy stops attaching credentials for the session within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).
The **Sessions** page shows each session as **Active**, **Revoked**, or **Expired**, and keeps expired and revoked sessions so you can audit what an agent had access to during the session:
<Frame>
<img src="/images/platform/agent-vault/sessions-list.png" alt="The Sessions page listing active, revoked, and expired sessions with their label, access bundle, and expiry" />
</Frame>
## Access changes
The access bundle and any inline services are chosen when you create the session and can't be changed afterwards. However, the proxy re-checks whether the agent still gets credentials once every [poll interval](/documentation/platform/agent-vault/proxies#poll-interval) (60 seconds by default). Here's how common access changes affect a session:
- If someone no longer has any grant on an access bundle, directly or through a group, their sessions for that bundle stop getting credentials
- If someone still has another grant on the bundle, such as through a group, revoking one grant doesn't affect their sessions
- If you delete an access bundle, every session scoped to it stops getting credentials (the session still lists the bundle's name, so you can see what it was)
- If you remove someone from Agent Vault, the proxy refuses every request on their sessions
- If the user or machine identity that created a session loses the **Admin** role in Agent Vault, the session stops getting credentials for its [inline services](/documentation/platform/agent-vault/inline-services)
None of these changes removes the [skills](/documentation/platform/agent-vault/skills) that the CLI already installed on the agent's host. To stop agents from using those skills, [delete the installed copies](/documentation/platform/agent-vault/skills#remove-installed-skills).
<Note>
If a session stops getting credentials because of a lost grant, a deleted bundle, or a lost **Admin** role, the proxy still forwards the agent's requests, without credentials. Whether those requests reach the upstream host depends on the proxy's [traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy).
</Note>
## Audit trail
When you create a session, change its label, or revoke it, Infisical writes an audit event. To review these events, open **Audit Logs** in Agent Vault, or scope an [audit log stream](/documentation/platform/audit-log-streams/audit-log-streams) to the Agent Vault product.
Audit events cover what you changed in Infisical. To see which requests an agent made while its session was running, [view its session logs](#view-session-logs).