> ## Documentation Index
> Fetch the complete documentation index at: https://browser-mcp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication, tokens, and OIDC

> Separate dashboard identity, extension pairing, and MCP authorization.

## Three distinct credentials

| Credential              | Purpose                                                      | Handling                                                                                                           |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Dashboard session       | Sign-in, browser management, device approval, admin settings | HttpOnly, SameSite Lax cookie; mutating dashboard routes require the same origin.                                  |
| `br_…` connection token | Authenticate the extension's browser WebSocket               | Browser-scoped; hashed at rest; sent in the first WebSocket message, not a query string.                           |
| `mcp_…` MCP token       | Authorize a client to control one registered browser         | Browser-scoped, shown once, SHA-256 hashed at rest, expiring and revocable; sent in the HTTP Authorization header. |

Never interchange token types. Both browser tokens and MCP tokens are bearer credentials: anyone holding one can exercise its authority. Browser scope means one browser registration, **not** a site, a tab, or read-only access.

## Community bootstrap

The first registered account becomes administrator atomically. Restrict access until your intended administrator has registered. Public email/password signup closes afterward; later users use OIDC. Existing password accounts can still sign in. Do not rely on obscurity of the hostname to protect the first-account race.

## Configure community OIDC

1. As administrator, open the OIDC settings in the dashboard.
2. Register a web client with your identity provider. Use this exact redirect URI for your deployment:

```text theme={null}
https://<your-host>/api/auth/oauth2/callback/oidc
```

3. Provide the **issuer URL**, client ID, and client secret, then enable OIDC. Use an absolute HTTPS issuer (localhost is permitted for development). The issuer must support standard OIDC discovery.
4. Save and verify a sign-in in a separate private browser window before ending your admin session. Keep a tested administrator recovery path.
5. Restrict who can use the application through your identity provider's assignment and sign-in policies. Enabling OIDC is not an invitation system.

The client secret is encrypted using `SETTINGS_ENCRYPTION_KEY`. The read API exposes `hasClientSecret`, never the stored secret. A blank or omitted client secret on update preserves the existing encrypted value; it does not clear it. Settings are community-admin-only. Managed builds use GitHub instead.

The admin API is `GET /api/admin/oidc` and `PUT /api/admin/oidc`. Updates use `{enabled, issuer, clientId, clientSecret?}` and require your authenticated admin session and the same origin. Do not send these credentials through MCP tools or untrusted browser pages.

## Device approval

The extension starts a request with a challenge derived from a random verifier. A signed-in user must explicitly approve it in the dashboard. The verifier is required to poll and redeem the connection credential once; the device code or approval link by itself is insufficient. Requests expire after ten minutes. Pending connection credentials are encrypted at rest until consumed.

Check the upstream hostname and requested device name, and decline requests you did not initiate. GitHub authentication is not itself permission to silently connect a browser.

## Create, expire, and revoke MCP tokens

Create a named token on a browser's dashboard page. Expiry is from 1 to 365 days. Copy the plaintext once into your client's secure credential store; it cannot be recovered from the token list. Create a separate token for each client so you can revoke it independently.

Use:

```http theme={null}
Authorization: Bearer <mcp-token>
```

against `/b/<browser-id>/mcp`. The server checks token validity and browser ownership on each request. Token revocation stops future authorized use; rotating a browser connection token disconnects the old browser connection and fails pending work. Avoid promises that revocation can undo browser actions already completed.

## Rotation and recovery

* Rotate an exposed MCP token by revoking it and issuing a replacement.
* Rotate an exposed connection token and re-pair the extension.
* Rotating `AUTH_SECRET` may invalidate sessions; plan user reauthentication.
* Do not casually change `SETTINGS_ENCRYPTION_KEY`: encrypted settings and pending device credentials require the original key. This version does not provide an automatic multi-key re-encryption workflow.
* A backup restore must include compatible database state and the encryption key. Keep secrets separate from ordinary backups and source control.