<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Agent Vault

## Introduction

Agent Vault is a password manager that your users share with their AI agents. A user saves a website login once, in a widget embedded in your application. After that, your agent can ask for a browser that is already signed in to that website and use it to read pages, click, and type for the user.

The agent never receives the password, the session cookies, or the browser itself. It works through a small set of tools that WorkOS checks on every call.

> Agent Vault must be enabled for your account. [Contact support](mailto:support@workos.com) to enable the feature before getting started.

## How it works

1. **User: saves a login.** Your application renders the Agent Vault widget with a widget token for the user. The user types the website address, username, and password into a frame served by WorkOS, so the password never passes through your application. WorkOS signs in to the website once to confirm the login works, then stores the password encrypted.
2. **Your server: creates a Space.** A Space is a browser that belongs to one user. WorkOS creates and runs it, or it can run in an [self-hosted browser](https://workos.com/docs/agent-vault/self-hosted-browser) that you operate.
3. **Your server: creates a grant for the agent.** A grant is a short-lived token that lets an agent use that user's Spaces and saved logins.
4. **Agent: connects a saved login and works.** The agent passes the grant to the Agent Vault MCP server. It asks WorkOS to sign the Space in with a saved login, then opens pages, reads them, and acts on them.

The [quick start](https://workos.com/docs/agent-vault/quick-start) walks through each step.

## Concepts

### Saved logins

A saved login is a website address, a username, and a password that one user saved. The API calls it a [credential](https://workos.com/docs/reference/agent-vault/credential). A saved login belongs to the user who saved it, in the organization they saved it in, and only that user's Spaces in that organization can use it.

Each saved login reports a `setup_state`:

| State             | Meaning                                                               |
| ----------------- | --------------------------------------------------------------------- |
| `pending`         | The login is saved and its first sign-in has not started.             |
| `connecting`      | WorkOS is signing in to the website.                                  |
| `connected`       | The last sign-in worked. An agent can use the login.                  |
| `needs_attention` | The last sign-in failed. The `failure_reason` field says what failed. |

Some websites can't be signed in to automatically. For those, the user signs in by hand in a live view of the browser, and WorkOS keeps the session that results.

### Spaces

A [Space](https://workos.com/docs/reference/agent-vault/space) is a browser session that belongs to one user. Your server creates it, an agent works in it, and your server closes it when the work is done.

A Space expires after ten minutes without browser work, such as opening a page, a click, or a sign-in. Each piece of work gives it ten more minutes, up to one hour after it was created. Closing a Space or deleting a saved login it uses ends the agent's access at once.

Each Space keeps the websites it is signed in to apart: one saved login gives the agent the pages of that website's origin and nothing else.

### Grants

A [grant](https://workos.com/docs/reference/agent-vault/grant) is a short-lived bearer token your server creates for one user. It lets an agent call the Agent Vault MCP server, and it can be bound to a single Space.

A grant lasts five minutes, and a grant bound to a Space never outlasts the Space. Create a new grant for each agent run.

## What an agent can do

An agent works in a Space through the [Agent Vault MCP tools](https://workos.com/docs/reference/agent-vault/mcp). It can:

- List the user's saved logins and sign the Space in with one of them.
- Open a page of the signed-in website.
- Read a page as text and a list of links, buttons, and fields.
- Click a link or button, and type into a field.
- Take a screenshot, with passwords, one-time codes, and credential-like fields masked. Other fields may be visible.

An agent cannot read or type a password, read cookies or storage, run scripts, or pick elements with its own selectors. It can only act on the controls WorkOS listed in the most recent read of the page.

## When a sign-in needs the person

Signing in is not always something WorkOS can finish alone. When an agent asks for a sign-in, the result tells it what to do:

- **A verification code.** The website sent the person a code. The agent asks the person for it and submits it.
- **Signing in by hand.** WorkOS could not finish the sign-in. The agent gets a short-lived link to the live browser and gives it to the person, who finishes signing in there.
- **Needs attention.** The sign-in failed for a reason the person has to fix, such as a changed password. The person retries or replaces the login in the widget.

## Authorization

Agent Vault acts for one user, so every request from your server carries your WorkOS API key and the user's ID. When the user works in an organization, the request also names the organization. WorkOS checks that the user belongs to the environment the API key is for and, when an organization is named, that the user is an active member of it. Your server decides who a request acts for, so send only the ID of the user who is signed in to your application.

The widget authenticates with a [widget token](https://workos.com/docs/widgets/tokens) that your server creates for the user and organization, or with the user's [AuthKit](https://workos.com/docs/authkit) access token. An access token from a session that started with [impersonation](https://workos.com/docs/authkit/impersonation) can't use Agent Vault.

Grants narrow that authority further. A grant carries no API key, expires in minutes, and stops working when the Space it is bound to ends, including when a saved login the Space is signed in with is deleted.
