auth/docs

00 / overview

One sign-in.
Every app.

auth is a private OpenID Connect provider. Apps send people here to sign in with Google, Microsoft, GitHub, a password or an email link, and get back a verified identity. Every login, failure and block is visible live in the admin.

issuer https://auth.brvo.app
protocolOIDC code + PKCEany standard library
sign-in5 methodsgoogle · microsoft · github · password · link
per appa clientredirect URIs, methods, allowlist

01 / quickstart

Three steps

  1. In the admin, apps → new app: name, type (server app = confidential, SPA/mobile = public), exact redirect URI(s). Copy the client secret: it is shown once.
  2. Point a maintained OIDC library at the issuer https://auth.brvo.app with PKCE, state and nonce on, scopes openid email profile.
  3. Key your users on the sub claim. Trust email only when email_verified is true. Register a back-channel logout URI so blocks reach your app at once.
AUTH_ISSUER=https://auth.brvo.app
AUTH_CLIENT_ID=…
AUTH_CLIENT_SECRET=…
AUTH_REDIRECT_URI=https://<app>/auth/callback

02 / endpoints

Discovery has them all

endpointuse
GET /.well-known/openid-configurationdiscovery
GET /authorizestart a login (code + PKCE S256)
POST /tokencode → tokens; refresh (rotating)
GET /userinfoprofile for an access token; checks blocks live
GET /jwksRS256 public keys
POST /revokerevoke a refresh token chain
GET /logoutRP-initiated logout

03 / what is enforced

Safe by default

  • PKCE S256 for every client, response_type=code only, exact redirect URI match, iss in every authorization response.
  • Codes live 60 s and work once; a replay revokes what the code produced. Refresh tokens rotate; reuse revokes the chain.
  • Identities are keyed by provider + subject. Email links accounts only when verified: Google email_verified, Microsoft personal accounts or xms_edov, GitHub verified primary.
  • Passwords: argon2id, at least 10 characters, common passwords refused, same answer for unknown accounts, per-account and per-IP throttling, automatic temporary IP blocks.
  • Blocking a user ends their sessions and refresh tokens and calls each app's back-channel logout.
  • Secrets at rest are hashed (codes, refresh tokens, client secrets, sessions) or sealed with AES-GCM (provider secrets, signing keys).

04 / full guide

auth.md: everything an AI agent needs

Give this file to the agent that wires up an app. Flow, claims, user mapping, logout, recipes for Node, Next.js, Expo and Go, and a ship checklist.

auth.md download

Loading auth.md…