# auth.md

Archboard runs its own OAuth 2.1 authorization server for AI agents and other MCP clients. People sign in with Google or GitHub; there are no Archboard passwords.

## For agents (MCP clients)

- Protected resource: https://getarchboard.app/mcp (metadata: https://getarchboard.app/.well-known/oauth-protected-resource/mcp)
- MCP server card: https://getarchboard.app/.well-known/mcp/server-card.json (transport, protocol versions, capabilities, and these OAuth endpoints)
- Authorization server metadata: https://getarchboard.app/.well-known/oauth-authorization-server (also https://getarchboard.app/.well-known/openid-configuration); issuer https://getarchboard.app
- Client registration: use a Client ID Metadata Document (an https URL as client_id; Archboard fetches it over https with size, time, and private-address limits), or dynamic client registration at https://getarchboard.app/oauth/reg for public clients only (token_endpoint_auth_method none; no client secret is issued). Redirect URIs must be https or loopback, or one of these exact desktop-app redirect URIs: cursor://anysphere.cursor-mcp/oauth/callback.
- Flow: authorization code with PKCE (S256 required) and the `resource` parameter set to https://getarchboard.app/mcp; https://getarchboard.app (the site-wide resource in https://getarchboard.app/.well-known/oauth-protected-resource) also works and yields the same token. The authorization response includes `iss` (RFC 9207)
- Scopes: diagrams:read, diagrams:write
- Tokens: opaque, short-lived access tokens. Refresh tokens are issued to clients registered with the refresh_token grant (offline_access is not required), rotate on every use, expire after 30 days without use, and stop working 90 days after the first authorization; then the client must authorize again
- Consent: the person signs in with Google or GitHub and approves your client by name, redirect host, and scopes, and chooses which organizations and workspaces it can use (all by default) and whether it may read, edit or delete in each (edit by default; delete, which moves diagrams to the trash, only when the person picks it)
- Access changes: the person can change those organizations, workspaces, and permissions, or rename the connection, under Settings → Connected apps; a call outside them returns `forbidden` with `details.reason: "grant_scope"`, and a call that needs more than the permission there returns `forbidden` with `details.reason: "grant_permission"`
- Revocation: https://getarchboard.app/oauth/token/revocation, or the person removes your app under Settings → Connected apps
- Image upload links: the `upload_image` tool returns an upload URL and a one-time token; the file goes up with PUT and the token only in the `X-Archboard-Upload-Token` header (no cookies, no CORS; requests with an `Origin` header are refused). The token places one image once in one diagram, is tied to the app connection and the access token that requested it, and expires after 5 minutes; only a hash of it is stored
- Export download links: the `export_diagram` tool returns a link that downloads one PNG or SVG file for 15 minutes and up to 5 downloads, without cookies or CORS; anyone with the link can use it until then. Only a hash of the token is stored, and removing the app, changing its access, or deleting, moving, or transferring the diagram ends the link
- Rate limits: tool calls are limited per user and per token, the image tools also have an image budget, and `export_diagram` an export budget; `rate_limited` errors include `retryAfterMs`
- Setup per app, tools, limits, and errors: https://getarchboard.app/developers/mcp.md

## What is public without a user session

- GET https://getarchboard.app/llms.txt (product facts)
- GET https://getarchboard.app/schemas/archboard-document-v2.json (document format; also archboard-ops-v1.json and archboard-clipboard-v1.json; policy: https://getarchboard.app/developers/format.md)
- Not listed here: the web app’s own API and health probes under /api/, and share links (/s/<token>). A share link opens for anyone who has it, without an account; share pages are not for crawling. robots.txt keeps crawlers out of /api/, /oauth/, and /s/. Those rules are for crawlers: MCP clients reach the OAuth and MCP endpoints above through the authorization flow the person starts, and use the upload and download links that MCP tools return.

## What is not here

- No password login and no API keys for agents
- No A2A agent card, x402, MPP, UCP, or ACP checkout

Paid seats go through Polar (human billing). Questions: hello@getarchboard.app.