A grant is a short-lived bearer token your server creates for one user. It lets an agent call the Agent Vault MCP server.
A grant can’t be read again or extended. It stops working when it expires or when the Space it is bound to ends.
Example grant
cURL
grant
Creates a grant that lets an agent call the Agent Vault MCP server for a user. A grant lasts five minutes.
cURL
| 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" | |
| }' |
| { | |
| "access_token": "<MCP grant>", | |
| "token_type": "Bearer", | |
| "expires_at": "2026-11-13T18:10:00.000Z" | |
| } |
POST/agent-vault /spaces /grants
Returns
- 400 Bad Request: the body is missing a field or has an unknown field.
- 401 Unauthorized: the user is not in the environment of the API key, or is not an active member of the organization.
- 403 Forbidden: the audience is not the Agent Vault MCP server, or the Space does not belong to the user or has ended.