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

# Agent registration reference

> The auth.md endpoints, registration methods, tokens, limits, errors, and revocation.

This reference gives the facts of agent registration. It follows the [auth.md protocol](https://github.com/workos/auth.md). For the steps, see [Register an agent](https://vms.dev/docs/api-reference/agent-registration.md). For the reasons behind the design, see [How agents get access](https://vms.dev/docs/explanation/agent-access.md).

Check a fact about agent registration.

Ask which endpoint, method, limit, or error I want to check.
Give me its facts from this reference.

## Discovery

| Document | URL |
| - | - |
| Agent instructions | `https://vms.dev/auth.md` |
| Protected Resource Metadata | `https://vms.dev/.well-known/oauth-protected-resource/api/mcp` |
| Authorization Server metadata | `https://vms.dev/api/auth/.well-known/oauth-authorization-server` and `https://vms.dev/.well-known/oauth-authorization-server/api/auth` |

The Authorization Server metadata has an `agent_auth` block with the endpoints, the methods, and `identity_assertion.trusted_issuers`.

## Endpoints

| Endpoint | Method | Use |
| - | - | - |
| `/api/auth/agent/identity` | `POST` | Register. Send `type`. |
| `/api/auth/agent/identity/claim` | `POST` | Start a claim, or get a new code. Send `claim_token` and `email`. |
| `/api/auth/oauth2/token` | `POST` | Exchange an assertion (`urn:ietf:params:oauth:grant-type:jwt-bearer`), or poll a claim (`urn:workos:agent-auth:grant-type:claim`). |
| `/api/auth/oauth2/revoke` | `POST` | Revoke one access token. |
| `/api/auth/agent/event/notify` | `POST` | Agent providers send revocation events (`application/secevent+jwt`). |

## Registration methods

All three methods are on.

| Method (`type`) | Body | Result | Claim |
| - | - | - | - |
| `identity_assertion` | `assertion_type: "urn:ietf:params:oauth:token-type:id-jag"`, `assertion` | An identity assertion at once. If the email has an account that is not linked to the provider, `401 interaction_required` with a claim. | Only to link an existing account |
| `service_auth` | `login_hint`: the email of the user | A claim. No credential before the claim. | Necessary |
| `anonymous` | none | An identity assertion at once, for an agent with no workspaces | Optional |

## ID-JAG rules

| Rule | Value |
| - | - |
| Issuer | Must be on the trust list, `agent_auth.identity_assertion.trusted_issuers` in the Authorization Server metadata. The keys come from `<issuer>/.well-known/jwks.json`. |
| JOSE `typ` | `oauth-id-jag+jwt` |
| `aud` | `https://vms.dev/api/mcp` |
| Identity | `email` with `email_verified: true` |
| Lifetime | `exp` no more than 10 minutes after `iat` |
| `auth_time` | Necessary. No more than 1 hour old, else `401 login_required` with `max_age: 3600`. |
| `jti` | Used one time only |

A new verified email gets a new account. A known `(iss, sub)` pair gets the account that it is linked to.

## Tokens and limits

| Item | Value |
| - | - |
| Scopes of each registration | `organization:read`, `workspace:read`. Pre-claim and post-claim scopes are the same. |
| Access token | A JWT for `https://vms.dev/api/mcp`. Works for 15 minutes. |
| Identity assertion | Works for 7 days. Exchange it again for each new access token. There is no refresh token. |
| User code | 6 digits. Works for 10 minutes. 5 wrong codes stop it. |
| Claim window | 24 hours from registration. An anonymous registration that is not claimed in this window stops working. |
| Poll interval | 5 seconds. A faster poll gets `slow_down`. |
| Rate limit | 30 requests in one minute for each agent endpoint |

A claim gives new tokens and makes the tokens from before the claim stop working.

## Revocation

| Layer | Who | Effect |
| - | - | - |
| One access token | The agent, at `/api/auth/oauth2/revoke` | That token stops. The assertion still works. |
| Registration | The agent provider, with a security event | Each registration for the `(iss, sub)` pair stops. `/oauth2/token` returns `invalid_grant`. |
| Registration | The user, with **Disconnect** on [Profile](https://vms.dev/docs/account/connect-agent.md#see-and-disconnect-your-agents) | The registration stops, and the link to the provider is removed. |

The security event must have the event `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked` with a subject `{ "format": "iss_sub", "iss", "sub" }`. A provider can revoke only its own subjects.

## Errors

| Code | Status | Where |
| - | - | - |
| `invalid_request` | 400 | Identity and claim endpoints |
| `issuer_not_enabled` | 400 | Identity endpoint |
| `interaction_required` | 401 | Identity endpoint (ID-JAG for an existing account) |
| `login_required` | 401 | Identity endpoint (old `auth_time`) |
| `invalid_claim_token` | 400 | Claim endpoint |
| `claimed_or_in_flight` | 409 | Claim endpoint |
| `claim_expired` | 410 | Claim endpoint |
| `invalid_grant`, `invalid_target`, `unsupported_grant_type`, `authorization_pending`, `slow_down`, `expired_token` | 400 | Token endpoint |

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


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