# Sign-in (OAuth 2.1) reference

Source: https://switchdesk.org/docs/ai/oauth

> How ChatGPT, Claude, Grok and Gemini sign in to SwitchDesk’s MCP server: user steps, discovery, CIMD and dynamic registration, PKCE, tokens, revocation.

## For people {#people}

1. In SwitchDesk: **Settings → AI Access → Connect an AI** → ChatGPT, Claude, Grok or Gemini → **What can it do?** → **Continue**. SwitchDesk keeps your choice for 15 minutes; there is no key.
2. In the other app, add `https://mcp.switchdesk.org/mcp` as a custom connector (the tile shows the exact menu).
3. The app opens SwitchDesk’s sign-in page. Enter your SwitchDesk email and the code we email you, then choose “Use the access you set on your Mac”, a preset, or Customize, and **Allow**. “Finish within 15 minutes.”

Signing in again from the same app replaces its old connection. Revoke in SwitchDesk ends it at once.

## Discovery {#discovery}

| Document | URL |
|---|---|
| Protected resource (RFC 9728) | `https://mcp.switchdesk.org/.well-known/oauth-protected-resource/mcp` |
| Authorization server (RFC 8414) | `https://mcp.switchdesk.org/.well-known/oauth-authorization-server` |

A request to `/mcp` without a token answers 401 with:

```text
WWW-Authenticate: Bearer resource_metadata="https://mcp.switchdesk.org/.well-known/oauth-protected-resource/mcp", scope="switchdesk"
```

- Issuer `https://mcp.switchdesk.org`; resource `https://mcp.switchdesk.org/mcp`; scope `switchdesk`.
- Endpoints: `/authorize`, `/token`, `/register`, `/revoke`.
- Authorization code + PKCE with `S256` only; `resource` on both requests; the redirect carries `iss`.
- Client auth: `none`, `client_secret_post`, `client_secret_basic`. No OpenID Connect document, no `offline_access`.

## Clients {#clients}

- **Client ID Metadata Documents** (preferred): an https `client_id` whose document allows `none`. Fetched over https only, from public addresses, no redirects, at most 16 KB, cached 5 minutes to 24 hours. A redirect is kept only if it is on the allowlist, loopback, or on the document’s own host.
- **Dynamic registration** (`POST /register`, RFC 7591): only with allowlisted redirects, or loopback (`http://127.0.0.1`, `http://localhost`, `http://[::1]`, any port). Unused registrations are removed after 24 hours.
- Known redirects (ChatGPT, Claude, grok.com, Gemini, Muse, Cursor, VS Code, Perplexity) mark a client verified. Any other client is shown as “Unverified app” with the host it sends you to.

## Tokens {#tokens}

| Token | Prefix | Lifetime |
|---|---|---|
| Authorization code | `sdg_` | 60 seconds, single use |
| Access token | `sdo_` | 1 hour, only for `https://mcp.switchdesk.org/mcp` |
| Refresh token | `sdr_` | Rotates on every use; the connection’s 90-day idle window |

- A retried or concurrent refresh within 60 seconds gets the same new pair. Reusing an older refresh token after that ends the connection.
- `POST /revoke` (RFC 7009): a refresh token ends the connection; an access token only itself.
- A replayed or failed code exchange spends the code; a replay also ends what it issued.