> ## 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. # 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 ## OpenAPI ````yaml POST /api/v1/agent-vault/sessions openapi: 3.0.3 info: title: Infisical API description: List of all available APIs that can be consumed version: 0.0.1 servers: - url: https://us.infisical.com description: Production server (US) - url: https://eu.infisical.com description: Production server (EU) - url: http://localhost:8080 description: Local server security: [] paths: /api/v1/agent-vault/sessions: post: tags: - Agent Vault Sessions description: >- 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 operationId: createAgentVaultSession requestBody: required: true content: application/json: schema: type: object properties: projectId: type: string minLength: 1 maxLength: 36 description: The ID of the Agent Vault project. accessBundle: type: string minLength: 1 maxLength: 64 description: >- The name of the access bundle this session carries. Leave it out to start a session with services of its own only. services: type: array items: anyOf: - type: object properties: type: type: string enum: - http description: >- The service type: `http` for an HTTP API, or `mcp` for a remote MCP server. Can't be changed after the service is created. name: type: string minLength: 1 maxLength: 64 description: >- A name for the service, shown in session logs and in the proxy's error messages. Lowercase letters, numbers and hyphens. Leave it out and the service goes by its first host. Either way, it can't match the name of another service in the session or in its access bundle. hostPattern: type: string maxLength: 1024 description: >- A comma-separated set of hosts this service covers, each optionally with a port (defaults to `443`). A leading `*.` wildcard matches exactly one label. Paths are not supported. allowedMethods: type: array items: type: string enum: - GET - HEAD - POST - PUT - PATCH - DELETE - OPTIONS minItems: 1 maxItems: 7 nullable: true description: >- The HTTP methods this service allows. Null allows every method. Anything else is refused by the proxy with a 403. allowedPathPrefixes: type: array items: type: string minItems: 1 maxItems: 20 nullable: true description: >- The path prefixes this service allows, matched on whole segments, so `/repos` covers `/repos/octo` but not `/repositories`. `null` allows every path. A path-restricted service also refuses any request whose path would have to be normalised to judge. credential: anyOf: - type: object properties: type: type: string enum: - bearer headerName: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$ description: >- The header the credential is written to. Defaults to `Authorization`. headerPrefix: type: string maxLength: 64 pattern: ^[^\x00-\x1f\x7f]*$ description: >- Written before the credential value, separated by one space. Leave empty for a header that carries the value alone, such as DD-API-KEY. Can't contain `{{` or `}}`. On update a field left out keeps its stored value, so send an empty string to clear the prefix when changing the header. value: type: string minLength: 1 maxLength: 8192 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The secret, sent exactly as given. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. required: - type - value additionalProperties: false title: Bearer - type: object properties: type: type: string enum: - basic username: type: string maxLength: 256 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The username half of the basic credential, sent exactly as given. May be empty if a password is set. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. password: type: string maxLength: 8192 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The password half of the basic credential, sent exactly as given. May be empty if a username is set. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. required: - type additionalProperties: false title: Basic Auth - type: object properties: type: type: string enum: - passthrough required: - type additionalProperties: false title: Pass-through customHeaders: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$ description: >- The name of the header, which must not be the credential's own header. prefix: type: string maxLength: 64 pattern: ^[^\x00-\x1f\x7f]*$ description: >- Written before the header value, separated by one space. Leave empty to send the value alone. Can't contain `{{` or `}}`. value: type: string minLength: 1 maxLength: 8192 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The header value, sent exactly as given. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. required: - name - value additionalProperties: false maxItems: 20 description: >- Additional headers the proxy attaches to every request to this service, on top of the credential. Up to 20. substitutions: type: array items: type: object properties: placeholder: type: string minLength: 1 maxLength: 255 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The fake value your agent already sends. The proxy replaces it with the real secret. Matched as a plain string, so a distinctive placeholder is worth choosing. Can't contain `{{` or `}}`. surfaces: type: array items: type: string enum: - path - query - header - body minItems: 1 maxItems: 4 description: >- Where in the request to look for the placeholder: path, query, header or body. value: type: string minLength: 1 maxLength: 8192 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The real value the placeholder is replaced with, sent exactly as given. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. required: - placeholder - surfaces - value additionalProperties: false maxItems: 20 description: >- Placeholders the proxy swaps for a real secret before forwarding. Up to 20. required: - type - hostPattern - credential additionalProperties: false title: HTTP service - type: object properties: type: type: string enum: - mcp description: >- The service type: `http` for an HTTP API, or `mcp` for a remote MCP server. Can't be changed after the service is created. name: type: string minLength: 1 maxLength: 64 description: >- A name for the service, shown in session logs and in the proxy's error messages. Lowercase letters, numbers and hyphens. Leave it out and the service goes by its first host. Either way, it can't match the name of another service in the session or in its access bundle. serverUrl: type: string minLength: 1 maxLength: 2048 description: >- The MCP server's URL, such as `https://mcp.example.com/mcp`. Must use `https`, with no username, password, query string or fragment. transport: type: string enum: - streamable-http - sse description: >- How the agent talks to the MCP server: `streamable-http`, or `sse` for the legacy HTTP+SSE transport. credential: anyOf: - type: object properties: type: type: string enum: - bearer headerName: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$ description: >- The header the credential is written to. Defaults to `Authorization`. headerPrefix: type: string maxLength: 64 pattern: ^[^\x00-\x1f\x7f]*$ description: >- Written before the credential value, separated by one space. Leave empty for a header that carries the value alone, such as DD-API-KEY. Can't contain `{{` or `}}`. On update a field left out keeps its stored value, so send an empty string to clear the prefix when changing the header. value: type: string minLength: 1 maxLength: 8192 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The secret, sent exactly as given. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. required: - type - value additionalProperties: false title: Bearer description: >- The credential the proxy attaches to requests to the MCP server, a bearer token. customHeaders: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$ description: >- The name of the header, which must not be the credential's own header. prefix: type: string maxLength: 64 pattern: ^[^\x00-\x1f\x7f]*$ description: >- Written before the header value, separated by one space. Leave empty to send the value alone. Can't contain `{{` or `}}`. value: type: string minLength: 1 maxLength: 8192 pattern: ^[^\x00-\x1f\x7f]*$ description: >- The header value, sent exactly as given. Services sent with a session can't use variables, so it can't wrap text in double braces. Never returned. required: - name - value additionalProperties: false maxItems: 20 description: >- Additional headers the proxy attaches to every request to this service, on top of the credential. Up to 20. required: - type - serverUrl - transport - credential additionalProperties: false title: MCP service maxItems: 20 description: >- 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. ttl: type: string description: >- 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: type: object properties: userId: type: string format: uuid description: The ID of the user to start the session on behalf of. userEmail: type: string format: email maxLength: 255 description: >- The email address of the user to start the session on behalf of. additionalProperties: false description: >- 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. example: userEmail: jsmith@example.com label: type: string maxLength: 128 nullable: true description: >- 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. additionalProperties: false example: projectId: 5f2c8a7e-1b3d-4e6f-9a0c-8d7b6e5f4a3c accessBundle: prod-deploy ttl: 8h label: Nightly deploy responses: '200': description: Default Response content: application/json: schema: type: object properties: session: type: object properties: id: type: string format: uuid description: The ID of the session. projectId: type: string format: uuid description: The ID of the Agent Vault project. label: type: string nullable: true description: >- 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. token: type: string description: >- The session token. Returned once, at mint, and never again. expiresAt: type: string format: date-time nullable: true description: When the session expires, or null when it never does. createdAt: type: string format: date-time accessBundle: type: object properties: id: type: string format: uuid nullable: true name: type: string required: - id - name additionalProperties: false nullable: true description: >- The access bundle this session carries. Null for a session with services of its own only. services: type: array items: type: object properties: id: type: string format: uuid description: The ID of the service sent with this session. name: type: string description: >- The name the service was sent with, or its first host if it was sent without one. Shown in session logs and in the proxy's error messages. type: type: string enum: - http - mcp description: >- The service type: `http` for an HTTP API, or `mcp` for a remote MCP server. Can't be changed after the service is created. serverUrl: type: string nullable: true description: >- The MCP server's full URL. Null for an `http` service. transport: type: string enum: - streamable-http - sse nullable: true description: >- How the agent talks to the MCP server: `streamable-http`, or `sse` for the legacy HTTP+SSE transport. Null for an `http` service. hostPattern: type: string description: >- A comma-separated set of hosts this service covers, each optionally with a port (defaults to `443`). A leading `*.` wildcard matches exactly one label. Paths are not supported. allowedMethods: type: array items: type: string enum: - GET - HEAD - POST - PUT - PATCH - DELETE - OPTIONS nullable: true description: >- The HTTP methods this service allows. Null allows every method. Anything else is refused by the proxy with a 403. allowedPathPrefixes: type: array items: type: string nullable: true description: >- The path prefixes this service allows, matched on whole segments, so `/repos` covers `/repos/octo` but not `/repositories`. `null` allows every path. A path-restricted service also refuses any request whose path would have to be normalised to judge. credential: anyOf: - type: object properties: type: type: string enum: - bearer headerName: type: string description: >- The header the credential is written to. Defaults to `Authorization`. headerPrefix: type: string description: >- Written before the credential value, separated by one space. Leave empty for a header that carries the value alone, such as DD-API-KEY. Can't contain `{{` or `}}`. On update a field left out keeps its stored value, so send an empty string to clear the prefix when changing the header. required: - type - headerName - headerPrefix additionalProperties: false title: Bearer - type: object properties: type: type: string enum: - basic required: - type additionalProperties: false title: Basic Auth - type: object properties: type: type: string enum: - passthrough required: - type additionalProperties: false title: Pass-through customHeaders: type: array items: type: object properties: name: type: string description: >- The name of the header, which must not be the credential's own header. prefix: type: string description: >- Written before the header value, separated by one space. Leave empty to send the value alone. Can't contain `{{` or `}}`. required: - name - prefix additionalProperties: false description: >- The headers the proxy attaches besides the credential, without their values. substitutions: type: array items: type: object properties: placeholder: type: string description: >- The fake value your agent already sends. The proxy replaces it with the real secret. Matched as a plain string, so a distinctive placeholder is worth choosing. Can't contain `{{` or `}}`. surfaces: type: array items: type: string enum: - path - query - header - body description: >- Where in the request to look for the placeholder: path, query, header or body. required: - placeholder - surfaces additionalProperties: false description: >- The placeholders the proxy swaps for a real secret, without their values. required: - id - name - type - serverUrl - transport - hostPattern - allowedMethods - allowedPathPrefixes - credential - customHeaders - substitutions additionalProperties: false description: >- The services sent with this session when it was created, without their secrets. Its access bundle's services aren't listed here. Empty when the session carries only an access bundle. required: - id - projectId - label - token - expiresAt - createdAt - accessBundle - services additionalProperties: false required: - session additionalProperties: false example: 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: [] '400': description: Default Response content: application/json: schema: type: object properties: reqId: type: string statusCode: type: number enum: - 400 message: type: string error: type: string details: {} required: - reqId - statusCode - message - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: reqId: type: string statusCode: type: number enum: - 401 message: type: string error: type: string required: - reqId - statusCode - message - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: reqId: type: string statusCode: type: number enum: - 403 message: type: string details: {} error: type: string required: - reqId - statusCode - message - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: reqId: type: string statusCode: type: number enum: - 404 message: type: string error: type: string required: - reqId - statusCode - message - error additionalProperties: false '422': description: Default Response content: application/json: schema: type: object properties: reqId: type: string statusCode: type: number enum: - 422 message: {} error: type: string required: - reqId - statusCode - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: reqId: type: string statusCode: type: number enum: - 500 message: type: string error: type: string required: - reqId - statusCode - message - error additionalProperties: false ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.