Skip to main content
A session is a time-bound grant scoped to one access bundle. Infisical returns a session token that identifies the session, and the agent uses that token to authenticate to the proxy on every outbound request. The proxy then attaches the real credential from the matching service at the network boundary. Every session is scoped to one access bundle and expires on a schedule you set. When the session expires (or you revoke it), the proxy stops attaching credentials to the agent’s requests within one poll interval.

​
Create a session

Anyone granted at least one access bundle can create a session. Admins can create one with any access bundle.
If you want to create sessions programmatically, you can have a machine identity create a new session for each run using the CLI, the API, or the Python SDK.
1
In Agent Vault, go to Sessions and select Create Session.
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 an access bundle picked, a label, and a seven day expiry
3
Copy the command shown. The session token appears once and can’t be retrieved again.
The Session Created dialog showing the run command with the session token shown once
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:
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 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, for example to record what the agent is working on

​
View session logs

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.
The Session Logs sheet for an active session, listing each request's time, method, host, path, upstream status, and outcome

​
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. 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, access bundle, and expiry

​
Access changes

The access bundle is 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 (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
None of these changes removes the skills that the CLI already installed on the agent’s host. To stop agents from using those skills, delete the installed copies.
If a session stops getting credentials because of a lost grant or a deleted bundle, the proxy still forwards the agent’s requests, without credentials. Whether those requests reach the upstream host depends on the proxy’s 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 Agent Vault, or scope an audit log stream 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.