Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

8.4 KB
Raw Blame
---
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).