A single source of truth for your OAuth implementation
OAuth 2.0 has many moving parts — grant types, scopes, token lifetimes, rotation, and a fixed vocabulary of error codes. Client developers integrating with your API need all of it in one place. This builder produces a concise, accurate specification you can drop straight into your developer docs.
How it works
You choose which grant types your authorization server supports and define your scopes and token policy. The tool renders a Markdown reference with these sections:
- Grant types — the selected flows, with a one-line note on when each applies. Authorization Code with PKCE for user-facing apps; Client Credentials for service-to-service.
- Scopes — the permission strings clients can request, each with a human description. Least privilege is the rule: grant the narrowest scope that does the job.
- Token lifetimes — access token TTL (kept short), refresh token TTL, and whether refresh tokens rotate on use.
- Error responses — the standard RFC 6749 token endpoint errors so client code can branch correctly.
The whole document is generated in your browser; nothing is sent to a server.
Scope design principles
Scopes define what a client is allowed to do, and they appear verbatim on the user consent screen. Design them for readability and minimal privilege:
- Use a
resource:actionformat such asorders:read,invoices:write, orusers:adminso the permission is self-explanatory. - Keep scopes stable once published — changing a scope name breaks all tokens that include it.
- Never create a catch-all scope like
all:access; bundle related scopes into a named compound scope if needed (for examplepayments:full), but keep it documented. - Document every scope in this spec so client developers know exactly what they can request and what consent the user will see.
Token lifetime guidance
| Token type | Typical TTL | Why |
|---|---|---|
| Access token | 5 – 60 minutes | Short lifetime limits exposure if a token leaks |
| Refresh token | 7 – 30 days | Long enough for convenience; short enough to reduce blast radius |
| Refresh token (rotation) | One use | Each use issues a new token; old one is revoked |
With rotation enabled, if a stolen refresh token is replayed after the legitimate client has already rotated, the server detects reuse and can revoke the entire token family and force re-authentication.
Design tips and worked example
Prefer Authorization Code with PKCE even for confidential web apps — it costs nothing and closes the code-interception attack. Reserve Client Credentials for back-end jobs that act as themselves, not on behalf of a user.
For example: a delivery-tracking API might support two grant types: Authorization Code with PKCE (for a customer-facing mobile app that tracks orders on behalf of a user) and Client Credentials (for an internal warehouse service that pushes status updates). The customer app gets orders:read and location:read; the warehouse service gets orders:write. Neither client can do more than its scopes allow.
Standard error vocabulary
The spec includes the RFC 6749 error codes so client developers know exactly which error value to branch on at the token endpoint:
| Error code | Meaning |
|---|---|
invalid_request | Malformed or missing parameter |
invalid_client | Client authentication failed |
invalid_grant | Authorization code or refresh token invalid, expired, or already used |
unauthorized_client | Client not permitted to use this grant type |
unsupported_grant_type | Grant type not supported by this server |
invalid_scope | Requested scope invalid or not granted |
Documenting these codes lets client teams write precise error-handling rather than generic “something went wrong” messages.