# MoveMentors auth.md You are an agent. This file tells you how to get permission to act for a person on MoveMentors, the booking platform for independent movement teachers (yoga, pilates, dance, breathwork and more) and small studios. The person can be a client who books classes, a mentor who teaches them, or a studio owner. Most lookups need no credentials at all. Searching mentors, studios and upcoming classes works anonymously through the public REST API at https://movementors.com/api/v1 (OpenAPI at https://movementors.com/api/v1/openapi.json, guide at https://movementors.com/developers). Only register when the person wants you to book, manage their classes, read their bookings, or anything else tied to their account. ## How registration works here MoveMentors uses standard OAuth 2.1. You register yourself as an OAuth client (no identity is asserted), then the person approves you in their browser. Nothing you hold works until they approve. - Identity type: `anonymous` registration, claimed by the person through browser consent. - Credential types: `access_token` (Bearer, 60 minutes) and `refresh_token` (30 days, rotated on every use). - Not supported: ID-JAG identity assertions, the email (service_auth) claim ceremony, the `/agent/identity` endpoint, client credentials, device authorization, and security event delivery. Don't try them. ## Step 1: Discover - Protected resource metadata for the MCP server (RFC 9728): https://movementors.com/.well-known/oauth-protected-resource/api/mcp - Protected resource metadata for the whole origin: https://movementors.com/.well-known/oauth-protected-resource - Authorization server metadata (RFC 8414), including the `agent_auth` block: https://movementors.com/.well-known/oauth-authorization-server An unauthenticated request to https://movementors.com/api/mcp answers 401 with `WWW-Authenticate: Bearer resource_metadata="https://movementors.com/.well-known/oauth-protected-resource/api/mcp"`. ## Step 2: Register a client (RFC 7591) ```http POST https://movementors.com/api/oauth/register Content-Type: application/json { "client_name": "Your agent name", "redirect_uris": ["http://127.0.0.1:33418/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "mcp:read mcp:write" } ``` - `redirect_uris`: 1 to 10 URLs, https, or http on a loopback address (127.0.0.1, ::1, localhost). - `token_endpoint_auth_method`: `none` for public clients (the usual case for desktop and CLI agents, PKCE proves possession), or `client_secret_basic` / `client_secret_post` for confidential clients. A `client_secret` is returned once, in this response only. - The response is 201 with your `client_id`. Registration is rate limited; reuse a client_id rather than registering again on every run. ## Step 3: Ask the person to approve you Send the person's browser to the authorization endpoint with PKCE (S256 is required; `plain` is rejected): ``` https://movementors.com/oauth/authorize?response_type=code&client_id=&redirect_uri=&scope=mcp%3Aread%20mcp%3Awrite&state=&code_challenge=&code_challenge_method=S256 ``` They sign in to MoveMentors (or create an account) and see a consent screen naming your client and the scopes. If they allow it, their browser returns to your `redirect_uri` with `code` and `state`. If they deny it, you get `error=access_denied`. The code is single use and expires after 10 minutes. ## Step 4: Exchange the code ```http POST https://movementors.com/api/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=&redirect_uri=&client_id=&code_verifier= ``` The response carries `access_token`, `token_type: "Bearer"`, `expires_in`, `refresh_token` and the granted `scope`. ## Step 5: Use the token Send it as `Authorization: Bearer ` to the MCP server at https://movementors.com/api/mcp (JSON-RPC 2.0 over Streamable HTTP). Call `tools/list` to see what this person's account can do; some tools only work for clients, mentors or studios. ## Step 6: Refresh ```http POST https://movementors.com/api/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=&client_id= ``` Each refresh returns a new refresh token and retires the old one. Store the new one. ## Scopes - `mcp:read`: Search the directory and read your own bookings, classes, schedules, financials, and messages. - `mcp:write`: Create and manage bookings, classes, schedules, expenses, and messages on your behalf. ## Revocation (RFC 7009) ```http POST https://movementors.com/api/oauth/revoke Content-Type: application/x-www-form-urlencoded token=&token_type_hint=refresh_token&client_id= ``` Confidential clients add `client_secret` in the form body. The endpoint answers 200 whether or not the token existed. ## Errors Token endpoint errors follow RFC 6749: `invalid_client`, `invalid_grant` (bad, expired or reused code or refresh token: start again at Step 3), `unsupported_grant_type`, `unauthorized_client`, `invalid_request`. A 401 from https://movementors.com/api/mcp means the access token is missing, expired or revoked: refresh once, and if that fails go back to Step 3. A 429 carries `Retry-After`. ## More - Connecting an AI assistant, for people: https://movementors.com/help/advanced/mcp-server - MCP server card: https://movementors.com/.well-known/mcp/server-card.json - Everything machine readable: https://movementors.com/.well-known/ai-catalog.json and https://movementors.com/llms.txt