Skip to content
BrokerrBrokerr

Hosted auth gateway

https://auth.brokerr.net is a stateless-from-the-client-perspective OAuth handoff service backed by short-lived encrypted sessions. Protocol version 1 is used by Brokerr.

Authorization sequence

Section titled “Authorization sequence”
  1. The local Brokerr instance requests a provider session.
  2. The gateway returns a random session ID, private claim secret, provider URL, and expiry. The claim secret stays on the initiating instance.
  3. The browser authorizes the provider and returns to the gateway callback.
  4. The gateway validates OAuth state, exchanges the code, encrypts the token bundle, and marks the session ready.
  5. The initiating instance polls with the claim secret, claims the bundle, validates provider identity, and stores credentials encrypted locally.
  6. Brokerr acknowledges delivery. The gateway deletes the encrypted token bundle and provider context from the session.

Canceled, denied, failed, expired, or acknowledged sessions cannot deliver a token.

Lifetimes

Section titled “Lifetimes”
  • Authorization session: 10 minutes by default.
  • Ready token bundle awaiting claim: 5 minutes by default.
  • Session audit metadata: 14 days by default, without token payloads.
  • Hosted refresh handle: 90 days by default and rotated after each successful refresh.

The gateway never returns a raw provider refresh token to Brokerr for supported hosted refresh providers. It returns an opaque encrypted handle with a server-tracked random ID. Used, revoked, or expired handles are rejected.

Gateway callbacks

Section titled “Gateway callbacks”
https://auth.brokerr.net/v1/callback/anilist
https://auth.brokerr.net/v1/callback/tmdb
https://auth.brokerr.net/v1/callback/letterboxd

These callbacks belong to the centrally operated provider applications. A user of hosted mode does not register them in a personal provider application.

Gateway hardening

Section titled “Gateway hardening”

Production startup fails unless public/provider URLs use HTTPS, API docs are disabled, trusted hosts are explicit, and forwarded addresses are trusted only from configured reverse proxies. Request body, target, and header sizes are bounded before route parsing.

OAuth operations use persistent per-client, per-session/handle, and global rate limits. Limiter keys are HMAC fingerprints rather than raw client addresses, session IDs, or refresh handles.

Security logs exclude OAuth query values, codes, states, session IDs, claim secrets, authorization headers, tokens, account IDs, and callback URLs. They are rotated daily, compressed, and retained for 14 days by default. These are operational security records, not usage analytics.