> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Register an agent with auth.md

> Let an AI agent register for a user, get a token, and call the MCP server, with no copied API key.

An agent can register for a user with the [auth.md protocol](https://github.com/workos/auth.md). Then it gets OAuth tokens for the MCP server. Most agents read the instructions at `https://vms.dev/auth.md` and do these steps without help.

Register this agent with VMS.

Read `https://vms.dev/auth.md` and follow it.
Use service\_auth with my email if you cannot mint an ID-JAG.
Show me the link and the code, and wait until I confirm.
Then call list\_organizations.

## Before you start

* For the `identity_assertion` method, the issuer of your agent provider must be on the trust list. See `agent_auth.identity_assertion.trusted_issuers` in the Authorization Server metadata. If your provider is not on it, use `service_auth` or `anonymous`.

## Register and get a token

**1. Discover the endpoints**

Get `https://vms.dev/api/auth/.well-known/oauth-authorization-server`. Read the `token_endpoint` and the `agent_auth` block.

**2. Register**

Send one of the three bodies to `/api/auth/agent/identity`:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/auth/agent/identity", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "service_auth", login_hint: "ada@example.com" }),
});
```

```bash cURL theme={null}
curl -X POST https://vms.dev/api/auth/agent/identity \
  -H "Content-Type: application/json" \
  -d '{ "type": "service_auth", "login_hint": "ada@example.com" }'
```

Use `identity_assertion` with an ID-JAG from a trusted provider, or `anonymous` if you know nothing about the user. See [Registration methods](https://vms.dev/docs/reference/agent-registration.md#registration-methods).

**3. Let the user confirm**

If the response has a `claim` block, show the user the `verification_uri` and the `user_code`. The user signs in and enters the code. See [Connect an AI agent with a code](https://vms.dev/docs/account/connect-agent.md).

Poll the token endpoint every 5 seconds:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/auth/oauth2/token", {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "urn:workos:agent-auth:grant-type:claim",
    claim_token: "clm_...",
  }),
});
```

```bash cURL theme={null}
curl -X POST https://vms.dev/api/auth/oauth2/token \
  -d grant_type=urn:workos:agent-auth:grant-type:claim \
  -d claim_token=clm_...
```

After the user confirms, the response has an `access_token` and an `identity_assertion`.

**4. Get a new access token**

When the access token expires after 15 minutes, exchange the identity assertion:

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/auth/oauth2/token", {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
    assertion: "<identity_assertion>",
    resource: "https://vms.dev/api/mcp",
  }),
});
```

```bash cURL theme={null}
curl -X POST https://vms.dev/api/auth/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=<identity_assertion> \
  -d resource=https://vms.dev/api/mcp
```

## Check the result

Send the access token as `Authorization: Bearer <access_token>` to `https://vms.dev/api/mcp` and call `list_organizations`. The result has the workspaces of the user. See the [MCP tools](https://vms.dev/docs/reference/workspace-mcp.md#tools).

For each endpoint, limit, and error, see the [agent registration reference](https://vms.dev/docs/reference/agent-registration.md).

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.