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

# Grant

A grant is a short-lived bearer token your server creates for one user. It lets an agent call the [Agent Vault MCP server](https://workos.com/docs/reference/agent-vault/mcp).

A grant can't be read again or extended. It stops working when it expires or when the Space it is bound to ends.

:::code-group{title="Example grant"}

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

:::

## Create a grant

Creates a grant that lets an agent call the [Agent Vault MCP server](https://workos.com/docs/reference/agent-vault/mcp) for a user. A grant lasts five minutes.

:::code-group{title="Create an MCP grant"}

```bash language="curl" title="Request" tab="1"
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 language="json" title="Response" tab="2"
{
  "access_token": "<MCP grant>",
  "token_type": "Bearer",
  "expires_at": "2026-11-13T18:10:00.000Z"
}
```

:::

### Error responses

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

### grant

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access_token` | string | Yes | The grant itself. |
| `token_type` | "Bearer" | Yes | Always `Bearer`. |
| `expires_at` | string | Yes | ISO 8601 timestamp of when the grant expires. |

### POST /agent-vault/spaces/grants

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | agent_vault_delegation.user_id |
| `organization_id` | string | No | agent_vault_delegation.organization_id |
| `audience` | string | Yes | The URL of the Agent Vault MCP server, `https://mcp.workos.com/agent-vault/mcp`. |
| `browser_space_id` | string | No | Binds the grant to one Space. A grant bound to a Space can only be used with that Space, and never outlasts it. |