# auth.md

## Audience

Software agents and developer tools that call webmcp.fast. There are two protected surfaces, and one credential never works on the other:

- **A relayed endpoint**, `https://<handle>.webmcp-gateway-preview.etadros.workers.dev/<device>/<server>/mcp`: one local MCP server on one of a user's devices. Scope `mcp`.
- **The management MCP server**, `https://webmcp-gateway-preview.etadros.workers.dev/mcp`. `check_handle`, `start_setup`, `setup_status` are anonymous; `list_devices` and `connect_url` need scope `manage`.

The public site, the docs and every discovery document need no credential.

## Discover

```http
GET https://webmcp-gateway-preview.etadros.workers.dev/.well-known/oauth-authorization-server
GET https://<handle>.webmcp-gateway-preview.etadros.workers.dev/.well-known/oauth-protected-resource/<device>/<server>/mcp
GET https://webmcp-gateway-preview.etadros.workers.dev/.well-known/oauth-protected-resource
```

The authorization server is the apex, https://webmcp-gateway-preview.etadros.workers.dev. An unauthenticated request to a protected endpoint, including `initialize`, answers `401` with `WWW-Authenticate: Bearer resource_metadata="..."` naming the RFC 9728 document for that exact endpoint. Bearer credentials are accepted only in the `Authorization` header. Endpoints never read cookies.

## Register

Dynamic client registration (RFC 7591) at `POST https://webmcp-gateway-preview.etadros.workers.dev/oauth/register`, or a Client ID Metadata Document URL as the `client_id`. No pre-registration, approval or API key is needed.

## Authorize: authorization code with PKCE S256

1. Generate a PKCE `code_verifier` and S256 `code_challenge`.
2. Open `https://webmcp-gateway-preview.etadros.workers.dev/oauth/authorize` with `response_type=code`, your `client_id`, a registered `redirect_uri`, the `scope`, the challenge, `code_challenge_method=S256`, `state`, and `resource` set to the exact MCP URL (RFC 8707).
3. The user signs in with a 6-digit code emailed to them and sees a consent screen naming that one endpoint. **This step is for the human.** An agent is never given the code and must not ask for it.
4. Exchange the returned code at `POST https://webmcp-gateway-preview.etadros.workers.dev/oauth/token` with `grant_type=authorization_code`, `client_id`, the same `redirect_uri` and the `code_verifier`.

Access tokens last one hour. Refresh tokens rotate on use. A grant lasts until the user disconnects it on the dashboard or removes the server or device.

## Scopes

| Scope | Grants |
|---|---|
| `mcp` | One relayed endpoint, named by `resource` and confirmed on the consent screen. The token's audience must equal the URL it is sent to. |
| `manage` | Reading the user's handles, devices and connector URLs through the management MCP server. |

## Use the credential

```http
POST https://<handle>.webmcp-gateway-preview.etadros.workers.dev/<device>/<server>/mcp
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Accept: application/json, text/event-stream
```

## Connector tokens

For a harness that cannot open a sign-in window, the user creates a connector token on https://webmcp-gateway-preview.etadros.workers.dev/app. It starts with `wmf_`, is shown once, is bound to one handle, device and server, and is sent as `Authorization: Bearer wmf_...`. It is revoked from the same page.

## Revoke

`POST https://webmcp-gateway-preview.etadros.workers.dev/oauth/token` implements RFC 7009 revocation. Users disconnect an agent on https://webmcp-gateway-preview.etadros.workers.dev/app, which revokes the grant and ends its sessions.

## The daemon

The daemon does not use OAuth. It pairs once (a device authorization flow shaped after RFC 8628, `POST https://webmcp-gateway-preview.etadros.workers.dev/api/v1/device/start` and `/poll`, approved by the human at https://webmcp-gateway-preview.etadros.workers.dev/activate) and then authenticates its WebSocket with an Ed25519 signature over a server challenge. See https://webmcp-gateway-preview.etadros.workers.dev/openapi.json.

## Contact

support@webmcp.fast. See also the [security model](https://webmcp-gateway-preview.etadros.workers.dev/docs/security-model) and the [privacy policy](https://webmcp-gateway-preview.etadros.workers.dev/privacy).