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

# Quick Start

## Before getting started

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

To get the most out of this guide, you'll need:

- A [WorkOS account](https://dashboard.workos.com/).
- An application that signs users in with WorkOS, in a staging environment.
- Your [API key](https://workos.com/docs/reference/api-authentication).
- Your application's origin, such as `https://app.example.com`, allowed for the widget. During the preview, WorkOS adds allowed origins for you.

Agent Vault acts for one user in one organization. Every request in this guide is made from your server with your API key, and names that user and organization.

## What you'll build

In this guide, you'll take one user from saving a website login to an agent working on that website:

- Show the widget where the user saves a login
- Create a Space, the browser the agent works in
- Create a grant and connect the agent to the Agent Vault MCP server
- Sign the Space in and read a page
- Handle a sign-in that needs the person
- Close the Space

## API object definitions

[Space](https://workos.com/docs/reference/agent-vault/space)
: A browser session that belongs to one user.

[Credential](https://workos.com/docs/reference/agent-vault/credential)
: A website login that one user saved.

[Grant](https://workos.com/docs/reference/agent-vault/grant)
: A short-lived token that lets an agent use the Agent Vault MCP server.

## Add Agent Vault to your app

### Let the user save a login

The user saves logins in the Agent Vault widget, a React component from [WorkOS Widgets](https://workos.com/docs/widgets). It lists the user's saved logins in your page. When the user adds a login, the widget opens a frame served by WorkOS, where the user types the password. Passwords go straight from that frame to WorkOS and never reach your page.

If your application doesn't use Widgets yet, follow the [Widgets quick start](https://workos.com/docs/widgets/quick-start) to install `@workos-inc/widgets` version 1.22.0 or later, import its styles, and render the `WorkOsWidgets` root component.

Install the stable 1.22.0 release with `npm install @workos-inc/widgets@1.22.0`.

On your server, create a widget token for the signed-in user and the organization they are working in.

```js title="Create a widget token"
const authToken = await workos.widgets.createToken({
  userId: user.id,
  organizationId,
});
```

Pass the token to your page and render the widget with it.

```jsx title="Render the widget"
import { AgentVault, WorkOsWidgets } from '@workos-inc/widgets';

export function SavedLogins({ authToken }) {
  return (
    <WorkOsWidgets>
      <AgentVault authToken={authToken} />
    </WorkOsWidgets>
  );
}
```

Saved logins belong to the user within the token's organization: the same user has a separate set in each organization. Send the same `organization_id` in the API requests below, so the agent sees the logins the user saved here.

A widget token expires after one hour. `authToken` also accepts a function that returns a fresh token. If your application uses AuthKit, you can pass the user's access token instead of a widget token.

### Create a Space

Create a Space for the user. WorkOS starts a browser for it and responds when the browser is ready.

```bash title="Create a Space"
curl --request POST \
  --url https://api.workos.com/agent-vault/spaces \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
    "name": "Shipping workspace"
  }'
```

```json title="Space"
{
  "object": "browser_space",
  "id": "bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC",
  "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "name": "Shipping workspace",
  "status": "ready",
  "expires_at": "2026-11-13T19:05:00.000Z",
  "cleanup_status": "none"
}
```

A `ready` Space has a browser but is not signed in to anything yet. The agent signs it in with a saved login.

A user can keep working in the same Space across several agent runs. [List the user's Spaces](https://workos.com/docs/reference/agent-vault/space/list) and reuse one that is `ready` before creating another.

### Create a grant for the agent

Create an MCP grant bound to the Space. The audience is the URL of the Agent Vault MCP server.

```bash title="Create an MCP grant"
curl --request POST \
  --url https://api.workos.com/agent-vault/spaces/grants \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
    "audience": "https://mcp.workos.com/agent-vault/mcp",
    "browser_space_id": "bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC"
  }'
```

```json title="MCP grant"
{
  "access_token": "<MCP grant>",
  "token_type": "Bearer",
  "expires_at": "2026-11-13T18:10:00.000Z"
}
```

The grant lasts five minutes, and a grant bound to a Space never outlasts the Space. Keep it on your server and create a new one for each agent run.

### Connect the agent

The Agent Vault MCP server is at `https://mcp.workos.com/agent-vault/mcp`. Connect to it with any MCP client that supports Streamable HTTP, and send the grant as a bearer token.

```js title="Connect to the MCP server"
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.workos.com/agent-vault/mcp'),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${grant.access_token}` },
    },
  },
);

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);
```

Give the server's tools to your model, or call them yourself. A typical run finds a saved login, signs the Space in with it, and then reads and acts on pages.

```js title="Sign in and read a page"
const spaceId = 'bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC';

const logins = await client.callTool({
  name: 'browser_credentials',
  arguments: {},
});
const credentialId = logins.structuredContent.data[0].id;

const login = await client.callTool({
  name: 'browser_login',
  arguments: { browser_space_id: spaceId, credential_id: credentialId },
});

if (login.structuredContent.status === 'connected') {
  await client.callTool({
    name: 'browser_navigate',
    arguments: {
      browser_space_id: spaceId,
      url: 'https://shipping.example.com/orders',
    },
  });

  const page = await client.callTool({
    name: 'browser_snapshot',
    arguments: { browser_space_id: spaceId },
  });
  console.log(page.structuredContent.elements);
}
```

`browser_snapshot` returns the page's text and its links, buttons, and fields as `elements`. Text entries have `role: "text"` and an empty `ref` and are for reading only. Pass only nonempty refs from actionable controls to `browser_click` or `browser_type`. A new snapshot replaces the refs of the one before it. The [MCP tools reference](https://workos.com/docs/reference/agent-vault/mcp) lists every tool.

### Handle a sign-in that needs the person

`browser_login` responds with one of three statuses:

| Status            | What to do                                                                                |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `connected`       | The Space is signed in. Continue with the task.                                           |
| `pending`         | The sign-in is still running. Call `browser_login` again with the same arguments.         |
| `needs_attention` | The sign-in failed. `reason` says why. The user retries or fixes the login in the widget. |

A `pending` result can include an `action` that the person has to take:

- `verification_code`: the website sent the person a code. Ask them for it, then call `browser_verification_code` with the code.
- `sign_in`: WorkOS could not finish signing in. Call `browser_sign_in_link` and give the person the link it returns. They finish signing in on that page and confirm.

After either action, call `browser_login` again until it responds with `connected` or `needs_attention`.

### Close the Space

When the work is done, close the Space. Closing it ends every grant bound to it and shuts down the browser WorkOS started for it.

```bash title="Close a Space"
curl --request DELETE \
  --url "https://api.workos.com/agent-vault/spaces/bspace_01JD3X9W4Q5Z8R7T6Y2N0M1KBC?user_id=user_01E4ZCR3C56J083X43JQXF3JK5&organization_id=org_01EHZNVPK3SFK441A1RGBFSHRT" \
  --header "Authorization: Bearer sk_example_123456789"
```

Users delete saved logins in the widget. Your server can also [delete a saved login](https://workos.com/docs/reference/agent-vault/credential/delete), which revokes every Space that uses it.
