OAuth apps
When to use one
Register an OAuth app when a third-party service needs to act on a Citadel user's behalf without holding their password. For machine-to-machine access (your own CLI / CI), use an agent token instead — it's a flatter contract.
Register
Settings → OAuth clients → New client. Set:
- Name. Shown to end-users on the consent screen — be honest.
- Type. Public (browser / mobile, no secret) or Confidential (server-side, secret stays server-side). The type is permanent — a client cannot be flipped after creation, see E-is_public_immutable.
- Redirect URIs. Whitelist of post-auth callback URLs. See E-redirect_uri_rules for the exact shape (HTTPS only except localhost / 127.0.0.1; no fragments; explicit list).
- Scopes. Discrete permission atoms per canon C15. Pick the minimum your integration needs.
Use the client
OAuth discovery lives at /.well-known/oauth-authorization-server. Most libraries consume that document automatically.
Rotate the secret
Confidential clients only. Settings → OAuth clients → row → Rotate secret. Step-up is required (recent MFA marker; see Two-factor auth). The new secret is shown once; the old secret stops authenticating immediately.
Public client info
Anyone can fetch a sanitised view of any active client at /api/oauth/clients/{client_id}/public — name, type, redirect URIs, owner — so the consent screen can render trusted metadata. Secrets and owner email are never returned.