Quick Start
Save a website login, create a Space, and let an agent work in a signed-in browser.
To get the most out of this guide, you’ll need:
- A WorkOS account.
- An application that signs users in with WorkOS, in a staging environment.
- Your API key.
- 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.
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
- Space
- A browser session that belongs to one user.
- Credential
- A website login that one user saved.
- Grant
- A short-lived token that lets an agent use the Agent Vault MCP server.
The user saves logins in the Agent Vault widget, a React component from WorkOS 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 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.
Pass the token to your page and render the widget with it.
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 for the user. WorkOS starts a browser for it and responds when the browser is ready.
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 and reuse one that is ready before creating another.
Create an MCP grant bound to the Space. The audience is the URL of the Agent Vault MCP server.
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.
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.
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.
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 lists every tool.
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 callbrowser_verification_codewith the code.sign_in: WorkOS could not finish signing in. Callbrowser_sign_in_linkand 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.
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.
Users delete saved logins in the widget. Your server can also delete a saved login, which revokes every Space that uses it.