> ## 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.

# How Agent Vault works

> The concepts Agent Vault uses to broker access to APIs, and how they combine at request time.

Agent Vault lets an AI agent make authenticated API calls without ever holding the real credentials. Instead, the agent routes its API calls through an Agent Vault proxy, which attaches the credentials on the way out.

```mermaid theme={"dark"}
flowchart LR
  subgraph private["Your private network"]
    agent["AI agent"]
    proxy["Agent Vault proxy"]
  end
  subgraph internet["Public internet"]
    apis["api.slack.com<br/>api.github.com<br/>..."]
  end
  infisical["Infisical"]
  agent -->|"request with a session token"| proxy
  proxy -->|"request with the credential"| apis
  proxy -->|"fetches the credentials this session may use"| infisical
```

## Mental model

Agent Vault uses four primitives to create secure sessions for AI agents:

* [**Services**](#services): The APIs, MCP servers, and anything else the agent talks to, with any credentials to add
* [**Access bundles**](#access-bundles): Groups of services, granted as a unit
* [**Sessions**](#sessions): Time-bound access grants that an agent uses to authenticate to the proxy for the services in an access bundle
* [**Proxies**](#proxies): The forward proxy that intercepts an agent's outbound traffic and attaches real credentials to authorized requests

Here's how the four concepts connect:

**Step 1**

The access bundle groups the services (external APIs or MCP servers) you want your agent to reach.

```mermaid theme={"dark"}
flowchart LR
  subgraph bundle["Access bundle"]
    s1["Service"]
    s2["Service"]
    s3["Service"]
  end
```

**Step 2**

You create a session for the bundle. Infisical returns a session token scoped to that bundle for a limited time.

```mermaid theme={"dark"}
flowchart LR
  token["Session token"] -->|"scoped to"| bundle
  subgraph bundle["Access bundle"]
    s1["Service"]
    s2["Service"]
    s3["Service"]
  end
```

**Step 3**

The agent runs with the session token and uses it to authenticate to the Agent Vault proxy on every outbound request.

```mermaid theme={"dark"}
flowchart LR
  agent["AI agent"] -->|"holds"| token["Session token"]
  token -->|"scoped to"| bundle
  subgraph bundle["Access bundle"]
    s1["Service"]
    s2["Service"]
    s3["Service"]
  end
```

**Step 4**

Every outbound request goes through the proxy, with the session token attached as the proxy credential.

```mermaid theme={"dark"}
flowchart LR
  agent["AI agent"] -->|"outbound request with session token"| proxy["Proxy"]
  agent -->|"holds"| token["Session token"]
  token -->|"scoped to"| bundle
  subgraph bundle["Access bundle"]
    s1["Service"]
    s2["Service"]
    s3["Service"]
  end
```

**Step 5**

The proxy reaches into the access bundle for the matching service's credential, attaches it, and forwards the request to the upstream host.

```mermaid theme={"dark"}
flowchart LR
  agent["AI agent"] -->|"outbound request with session token"| proxy["Proxy"]
  agent -->|"holds"| token["Session token"]
  proxy -->|"request with real credentials"| apis["External API"]
  proxy -->|"reads credentials from"| bundle
  token -->|"scoped to"| bundle
  subgraph bundle["Access bundle"]
    s1["Service"]
    s2["Service"]
    s3["Service"]
  end
```

This process allows the agent to authenticate to external APIs, all without having access to any of their real credentials.

## Concepts

Here's a breakdown of each primitive that Agent Vault relies on.

### Services

A service represents one external system that an agent can reach, such as GitHub's REST API or Linear's MCP server. Each service holds:

* **Target**: Where the system is, such as the host `api.github.com` or the server URL `https://mcp.linear.app/mcp`
* **Credential**: The real token, username and password, or OAuth authorization that the proxy attaches to the agent's requests, if the service uses one
* **Rules** (HTTP APIs): The HTTP methods and paths the service allows
* **Custom headers**: Extra headers the proxy adds to each request
* **Substitutions** (HTTP APIs): Placeholders the proxy replaces with real values

Agent Vault supports two types of service: [HTTP APIs](https://infisical.com/docs/documentation/platform/agent-vault/http-apis.md) and [MCP servers](https://infisical.com/docs/documentation/platform/agent-vault/mcp-servers.md).

You don't hand services to an agent directly—they're defined within access bundles.

> **[Services](https://infisical.com/docs/documentation/platform/agent-vault/services)**
>
> Anything an AI agent talks to during a session, such as an API or an MCP server.

### Access bundles

An access bundle groups a set of services under one name. A **code-review** bundle might hold services for GitHub, Slack, and Anthropic. An **on-call** bundle might hold services for PagerDuty, Datadog, and Slack.

You grant a bundle to a user, group, or machine identity. Anyone holding that grant can create sessions that reference it.

> **[Access bundles](https://infisical.com/docs/documentation/platform/agent-vault/access-bundles.md)**
>
> Lists of services that AI agents can access during a session.

### Sessions

A session is a time-bound access grant that's scoped to one access bundle. Infisical returns a session token that identifies the session; the agent uses that token to authenticate to the Agent Vault proxy on every outbound request.

When you create a session, you pick one access bundle and set an expiry. The agent never sees the real credentials inside the bundle. All it has is the session token, which only works when the proxy can authorize it against a live session.

Even if an attacker stole the session token, they could only reach the hosts, methods, and paths that the access bundle's services allow, and only until the session expires or you revoke it.

> **[Sessions](https://infisical.com/docs/documentation/platform/agent-vault/sessions)**
>
> Time-bound grants that let AI agents access services without holding real credentials.

### Proxies

A proxy runs where your agent's traffic leaves your network. It intercepts every outbound request, authorizes the request against the session's access bundle, attaches the matching service's credential as a header, and forwards the request to the upstream host. If the request breaks the matching service's [method or path rules](https://infisical.com/docs/documentation/platform/agent-vault/http-apis.md#methods-and-paths), the proxy refuses it instead.

> **[Proxies](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md)**
>
> Forward proxies that intercept an AI agent's requests and attach real credentials on the way out.

## Example flow: GitHub API

Here's what happens when an agent calls `api.github.com` through an Agent Vault session:

1. The agent's HTTPS client routes the request through the [proxy](#proxies) (because the `HTTPS_PROXY` environment variable points at it), including the [session](#sessions) token as the proxy credential.
2. The proxy looks up the session with Infisical, checking if it's still live and which [access bundle](#access-bundles) it carries.
3. The proxy looks inside the session's access bundle and finds a [service](#services) whose host pattern covers `api.github.com`. If the service limits methods or paths, the proxy refuses a request that doesn't match them. The proxy reads the real GitHub token from that service.
4. The proxy opens a new HTTPS connection to `api.github.com`, attaches the real token in the authorization header, and forwards the request.
5. GitHub responds. The proxy pipes the response back to the agent.

> [!NOTE]
>
> If the agent asks for a host that isn't covered by any service in the access bundle (like `api.internal.example.com`), the proxy either forwards the request without credentials or refuses it outright, depending on its [traffic policy](https://infisical.com/docs/documentation/platform/agent-vault/proxies.md#traffic-policy).

## Example flow: Linear MCP server

Here's what happens when an agent calls a tool on Linear's MCP server through an Agent Vault session. The agent has the server's real URL, `https://mcp.linear.app/mcp`, and no credential for it:

1. The agent's MCP client sends the tool call to `mcp.linear.app` through the [proxy](#proxies), with the [session](#sessions) token as the proxy credential.
2. The proxy finds the MCP [service](#services) in the session's [access bundle](#access-bundles) that covers `mcp.linear.app`, and reads the OAuth access token Infisical holds for it.
3. The proxy records the tool's name for the session log, attaches the access token, and forwards the request.
4. Linear responds, and the proxy pipes the response back to the agent.

Infisical refreshes the access token before it expires. If Linear rejects the token anyway, the proxy gets a fresh one from Infisical and retries the request once. The agent never signs in to Linear itself.

## Why no code changes are needed

Agent Vault plugs into a mechanism the entire HTTP ecosystem already uses: the `HTTPS_PROXY` environment variable. Any HTTP client that reads `HTTPS_PROXY` routes through the proxy without any code changes. That includes `curl`, `git`, `gh`, Python's `requests`, and most SDKs.

`infisical agent-vault run` sets `HTTPS_PROXY` for the agent, trusts the proxy's certificate authority, and passes the session token as the proxy credential. Everything the agent does after that works without needing to update any code.

> [!NOTE]
>
> Node.js's built-in `fetch` (undici-backed) doesn't read `HTTPS_PROXY` by default. If your agent uses it directly, run Node with `--use-env-proxy` or set `NODE_USE_ENV_PROXY=1` (Node 24 or later). Third-party clients like `axios`, `node-fetch`, and `got` honor the env vars without extra flags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.