> ## Documentation Index > Fetch the complete documentation index at: https://infisical.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Sessions > Time-bound grants that let AI agents access services without holding real credentials. A session is a time-bound grant in an [Agent Vault project](https://infisical.com/docs/documentation/platform/agent-vault/projects.md). It's scoped to one [access bundle](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md), to [inline services](https://infisical.com/docs/documentation/platform/agent-vault/inline-services.md) 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](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md) on every outbound request. The proxy then attaches the real credential from the matching [service](https://infisical.com/docs/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](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#poll-interval). A session only works through a proxy in the same project as its access bundle. ## Create a session Anyone granted at least one access bundle in a project can create a session in that project. Admins of the project can create one with any of its access bundles. > [!TIP] > > If you want to create sessions programmatically, you can have a [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) create a new session for each run using [the CLI](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md), [the API](https://infisical.com/docs/documentation/platform/agent-vault/sessions-api.md), [the Python SDK](https://infisical.com/docs/sdks/languages/python.md#agent_vault-sessions), or [the Node.js SDK](https://infisical.com/docs/sdks/languages/node.md#agentvault-sessions). A machine identity can also create sessions [on behalf of users](https://infisical.com/docs/documentation/platform/agent-vault/sessions-on-behalf-of-users.md), so that each agent uses the personal values of the person it runs for and gets no more access than that person. > [tab] Dashboard > > **Step 1** > > In your Agent Vault project, go to **Sessions** and select **Create Session**. > > **Step 2** > > 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**. > > ![The Create Session dialog with the on-call access bundle picked, Incident bot as the label, and a seven day expiry](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/session-create.png) > > **Step 3** > > Copy the command shown. The session token appears once and can't be retrieved again. > > ![The Session Created dialog showing the infisical agent-vault run command with the session token, which is shown once](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/session-created.png) > > 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 theme={"dark"} > export INFISICAL_AGENT_VAULT_SESSION_TOKEN= > infisical agent-vault run --proxy -- claude > ``` > [tab] CLI > > [`infisical agent-vault sessions create`](https://infisical.com/docs/cli/reference#agent-vault-sessions-create) creates a session with the access bundle you name and prints the session token. Replace `` with the ID of your Agent Vault project ([find the project ID](https://infisical.com/docs/documentation/platform/agent-vault/projects.md#find-the-project-id)): > > ```bash theme={"dark"} > export INFISICAL_AGENT_VAULT_PROJECT_ID= > infisical agent-vault sessions create --access-bundle --ttl 8h > ``` > > Set the duration with `--ttl`, which takes a value like `30m`, `8h`, `7d`, or `never`, and defaults to `never`. To [label the session](#label-a-session), pass `--label`. > > To create a session and start the agent in one command, pass the access bundle to `infisical agent-vault run` instead. The CLI revokes that session when the agent exits: > > ```bash theme={"dark"} > infisical agent-vault run --access-bundle --proxy -- > ``` > > 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). For a full example, see [Create sessions with the CLI](https://infisical.com/docs/documentation/platform/agent-vault/sessions-cli.md). > [tab] API > > Call [the endpoint that creates a session](https://infisical.com/docs/api-reference/endpoints/agent-vault-sessions/create.md) with the ID of your Agent Vault project, the access bundle's name, a `ttl`, and optionally a `label`: > > ```bash theme={"dark"} > curl -X POST https://app.infisical.com/api/v1/agent-vault/sessions \ > -H "Authorization: Bearer " \ > -H "Content-Type: application/json" \ > -d '{"projectId": "", "accessBundle": "", "ttl": "1h", "label": "nightly deploy"}' > ``` > > The response includes the session token. > [!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. ## 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 your Agent Vault project, 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](https://infisical.com/docs/api-reference/endpoints/agent-vault-sessions/update.md), for example to record what the agent is working on ![The Sessions page with the menu of the Nightly deploy session open, showing View Session Logs, Edit Label, and Revoke Session](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/session-actions.png) ## View session logs [Session logs](https://infisical.com/docs/documentation/platform/agent-vault/session-logs.md) record every request an agent makes during a session. To view them, go to **Sessions** in your Agent Vault project 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. ![The Session Logs sheet for the Review PR #1486 session, listing each request's time, method, host, path, upstream status, and outcome: brokered requests to GitHub, Anthropic, and Slack, a DELETE blocked by the service's method rules, and requests to registry.npmjs.org and pastebin.com blocked by the proxy's traffic policy](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/session-logs-view.png) ## Revoke a session To revoke a session before it expires, go to **Sessions** in your Agent Vault project, open the session's menu, and select **Revoke Session**. The proxy stops attaching credentials for the session within one [poll interval](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#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: ![The Sessions page listing active, revoked, and expired sessions with their label, identity, access bundle, creation time, and expiry, including a release-bot session on behalf of a user and a session with an inline service](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/agent-vault/sessions-list.png) ## 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](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#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 the project, the proxy refuses every request on their sessions * If the user or machine identity that created a session loses the **Admin** role in the project, the session stops getting credentials for its [inline services](https://infisical.com/docs/documentation/platform/agent-vault/inline-services.md) None of these changes removes the [skills](https://infisical.com/docs/documentation/platform/agent-vault/skills.md) that the CLI already installed on the agent's host. To stop agents from using those skills, [delete the installed copies](https://infisical.com/docs/documentation/platform/agent-vault/skills.md#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](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#traffic-policy). ## 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 your Agent Vault project, or scope an [audit log stream](https://infisical.com/docs/documentation/platform/audit-log-streams/audit-log-streams.md) 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). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.