Create session

Create an Agent Vault session with an access bundle you can reach, services of its own (Agent Vault admins), or both, for yourself or, as a machine identity with a delegation, on behalf of a user

POST /api/v1/agent-vault/sessions

cURL

cURL

curl --request POST \
  --url https://us.infisical.com/api/v1/agent-vault/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "5f2c8a7e-1b3d-4e6f-9a0c-8d7b6e5f4a3c",
  "accessBundle": "prod-deploy",
  "ttl": "8h",
  "label": "Nightly deploy"
}
'

200

{
  "session": {
    "id": "d1f0b5a2-6c3e-4f8a-9b7d-2e4c6a8f0b13",
    "projectId": "5f2c8a7e-1b3d-4e6f-9a0c-8d7b6e5f4a3c",
    "label": "Nightly deploy",
    "token": "agv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expiresAt": "2026-11-01T02:00:00.000Z",
    "createdAt": "2026-10-31T18:00:00.000Z",
    "accessBundle": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "prod-deploy"
    },
    "services": []
  }
}

Body

application/json

projectId · string

The ID of the Agent Vault project.

Required string length: 1 - 36

accessBundle · string

The name of the access bundle this session carries. Leave it out to start a session with services of its own only.

Required string length: 1 - 64

services · (HTTP service · object | MCP service · object)[]

Services this session carries itself, alongside its access bundle's or without one. Agent Vault admins only, up to 20. Each takes the same fields as a service in an access bundle, with three differences: the name is optional, every value is sent exactly as given because variables aren't available, and no field can be left to members. They belong to this session only and can't be edited. Their credentials, custom header values and substitution values are deleted when the session is revoked, or within an hour after it expires.

Maximum array length: 20

HTTP service

MCP service

Show child attributes

ttl · string

How long the session lasts: a duration such as 30m, 8h or 7d (at least 1m), or never. Defaults to 7d, or to 1h for a session started on behalf of a user.

onBehalfOf · object

Start the session on behalf of a user instead of yourself. Only a machine identity whose delegation covers the user can do this. The session can use only an access bundle that both the user and the machine identity can use, and it uses the user's personal values. The session still belongs to the machine identity, so only the machine identity and Agent Vault admins can see it and its session logs, not the user. Name the user by userId or by userEmail, not both.

Show child attributes

Example:

{ "userEmail": "[e-mail]" }

label · string | null

A short description of what the session is for, such as nightly deploy or support ticket triage. Up to 128 characters, without line breaks, tabs, or invisible characters. Shown wherever the session is listed.

Maximum string length: 128

Response

200

application/json

Default Response

session · object · required

Show child attributes