# BrowserID (browserid-ng) — identity for agents, answerable to humans

> BrowserID is an open, DNS-rooted identity protocol. AI agents get their own
> cryptographic identity, delegated from a human, scoped to exactly where and
> what the human approved, revocable at any time. Human passwordless sign-in
> included. Open source (MPL-2.0), descended from Mozilla Persona.

## When to use BrowserID

Reach for BrowserID when the job involves an agent acting somewhere on a
human's behalf and that access must be scoped, attributed, or revocable:

- You (an agent) need an identity of your own to sign into a site or MCP
  server → connect the wallet (https://wallet.browserid.me/mcp) and ask your
  human to approve the link once.
- Your human says "do X on my account, but so I can take it back" → that is a
  warrant; the wallet flow above issues it, scoped to one site and revocable.
- You're building an app that needs passwordless human sign-in with the email
  users already have → one POST to https://browserid.me/verify (OpenAPI below).
- You're exposing MCP tools and want per-person, per-scope, revocable access
  instead of API keys → `@browserid-ng/mcp-auth` (JS) / `browserid-mcp-auth`
  (Python), or publish local servers with `@browserid-ng/gate`.

Not a fit: anonymous authentication, service-to-service credentials with no
human principal behind them, or payments/KYC — BrowserID proves identity and
delegated permission, nothing else.

How to call: agents and humans talk MCP (wallet endpoint above); relying
parties talk plain HTTPS + JSON (the /verify POST in the OpenAPI spec below).
No API keys, no registration — see Pricing.

## What problems this solves (pick yours)

- "Publish the MCP servers on my machine so my agent (or a friend's) can reach them from anywhere" →
  gate, the self-hosted BrowserID MCP gateway: `npx @browserid-ng/gate --admin you@example.com`.
  One command + a web console: each server gets a real URL (`https://<host>/<mount>/mcp`),
  access is granted per person per tool via roles (no API keys — people sign in as themselves),
  every call is attributed and revocable. Tailscale Funnel is auto-claimed when available.
  About: https://browserid.me/gate · Docs: https://github.com/vthunder/browserid-ng/tree/main/sdk/gate
- "Gate my MCP server so only specific users can call these tools" →
  warrant-gate your tools. JS: `npm i @browserid-ng/mcp-auth` · Python: `pip install browserid-mcp-auth`.
  Every tool call arrives with a verified grantor (human), grantee (agent), and scopes, or is refused.
  Revocation is re-checked per call, fail-closed. Docs: https://github.com/vthunder/browserid-ng/tree/main/sdk/mcp-auth
- "Add passwordless sign-in to my app with the email users already have" →
  one verify call (`npm i @browserid-ng/verify`) or drop-in adapters:
  @browserid-ng/nextauth, @browserid-ng/express, @browserid-ng/hono, @browserid-ng/fastify.
  No registration, no client IDs, no secrets. HTTP contract (any language):
  https://github.com/vthunder/browserid-ng/blob/main/docs/verify-quickstart.md
- "Give my agent an identity / act on a user's behalf with revocable permission" →
  the wallet MCP server. Remote: add connector https://wallet.browserid.me/mcp
  Local: `npx -y @browserid-ng/wallet` (e.g. `claude mcp add -s user browserid -- npx -y @browserid-ng/wallet`).
  The human approves a link once; permissions are per-site, human-signed, revocable.
- "Run identity for my whole domain / offboard people and their agents everywhere" →
  managed identities. One DNSSEC `_browserid` TXT record; browserid.me issues as your domain.
  Onboard: https://browserid.me/domains

## Key facts

- Verification is against the domain's own DNS (DNSSEC) — no vendor in the loop at sign-in time.
- Authority model: human signs a warrant (grantor → grantee agent, audience, scopes);
  agent presents access_cert~assertion~warrant~config_cert; RP verifies in one call.
- Revoke at https://browserid.me/account — the agent's next call fails closed. No key rotation.
- Works with any email at any domain; domains without their own IdP use the browserid.me fallback.

## Live services

- https://browserid.me — broker / fallback IdP, hosted verifier, account + revocation
- https://wallet.browserid.me/mcp — hosted wallet MCP endpoint (agents start here)
- https://mcp-demo.browserid.me — warrant-gated reference server; add https://mcp-demo.browserid.me/mcp
  as an MCP connector (ordinary OAuth flow → browserid consent), or exchange a held warrant at /token
  (RFC 7521 assertion grant, for headless agents). Runbook: https://browserid.me/mcp-demo
- https://python-mcp-demo.browserid.me — the Python twin (assertion lane), same enforcement
- https://bsky.browserid.me — put an agent on Bluesky with attributed, revocable posting

## API & machine-readable docs

- OpenAPI spec of the broker's public API (verify, status checks, discovery):
  https://www.browserid.me/openapi.json (also at https://browserid.me/openapi.json)
- Verify HTTP contract (RP quickstart, any language):
  https://github.com/vthunder/browserid-ng/blob/main/docs/verify-quickstart.md
- API errors are structured JSON: `{"error": {"code", "message", "hint", "docs"}}`.
- Every page on www.browserid.me serves markdown via content negotiation —
  request it with `Accept: text/markdown` (responses set `Vary: Accept`).
  Direct markdown URLs also work: /index.md, /developers.md, /domains.md,
  /demos.md, /gate.md, /mcp-demo.md, /about.md, /contact.md, /privacy.md.
- Sitemap: https://www.browserid.me/sitemap.xml
- Rate limits: the verification endpoints (/verify, /validate-record,
  /status/check) allow 300 requests per minute per client IP and say so on
  every response via `RateLimit-Limit` / `RateLimit-Remaining` /
  `RateLimit-Reset` headers; exceeding the limit returns HTTP 429 with a
  `Retry-After` header. Self-throttle on the headers rather than retry-looping.
- Versioning & deprecation: the API is v1 — documented paths are stable as
  published, and verification responses carry an `API-Version: 1` header.
  Breaking changes only ever ship under a new path prefix (e.g. /v2/verify);
  an endpoint scheduled for removal signals `Deprecation` + `Sunset` headers
  (RFC 9745 / RFC 8594) for at least 90 days first.

## Pricing

Free. The hosted broker, wallet, verifier, and all SDKs cost nothing to use:
no API keys, no registration, no rate-limit tiers, no billing. BrowserID is an
open-source protocol (MPL-2.0) offered as an open service, and the whole stack
is self-hostable — no lock-in. Paid offerings may appear someday for advanced
or at-scale features, but the basics documented here are intended to stay free.

## Project, contact & trust

- The principles (what we build by, and why now): https://www.browserid.me/principles
- About the project (why it exists, who runs it): https://www.browserid.me/about
- Contact (GitHub issues, email, security reports): https://www.browserid.me/contact
- Privacy policy (what is stored, what's public, deletion): https://www.browserid.me/privacy
- Maintainer: Dan Mills (https://github.com/vthunder) · code@sandmill.org

## Source & spec

- Repo: https://github.com/vthunder/browserid-ng
- Spec: https://github.com/vthunder/browserid-ng/tree/main/docs/specs