Skip to main content
An agent can register for a user with the auth.md protocol. 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.

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:
Use identity_assertion with an ID-JAG from a trusted provider, or anonymous if you know nothing about the user. See 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.Poll the token endpoint every 5 seconds:
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:

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. For each endpoint, limit, and error, see the agent registration reference.