chore(other): update docs with refresh token grant type - #20
Merged
Conversation
![redocly[bot]](https://avatars.githubusercontent.com/in/348054?s=60&v=4){kind=small}
There was a problem hiding this comment.
cafe AI Review: 🟢 Completed
Redocly Agent has reviewed your changes and found 27 potential issue(s).
Note
Low Risk
These changes update OpenAPI documentation schemas. The risk is minimal as they do not alter application runtime behavior, only API references and potential client generation.
Overview
Updates OpenAPI definitions to detail the refresh_token grant type and clarify OAuth2 registration defaults.
- Enhances the OAuth2 security scheme description with non-standard behaviors (error formats, token rotation, and non-registrable refresh tokens) and adds a
refreshUrl. - Adds explicit default values for
redirectUris,scopes, andgrantTypesto theRegisterClientObjectschema. - Refines the
/oauth2/registerendpoint documentation, adds anauthorization_codeclient example, and removes an unused401response.
JLekawa
approved these changes
Aug 19, 2026
vadyvas
approved these changes
Aug 19, 2026
|
|
||
| Two behaviors do not conform to the specifications: | ||
|
|
||
| - **Errors use RFC 9457 problem+json, not RFC 6749 Section 5.2.** Failures return `application/problem+json` with `type`, `title`, `status`, and `instance`. There is no `error` or `error_description` field, so the standard codes (`invalid_grant`, `invalid_client`, `unsupported_grant_type`) never appear — branch on the HTTP status and `title` instead. A refresh token that is expired, already rotated, or unrecognized returns `400` with a `title` of `Refresh token has expired` or `Invalid refresh token`, where a conformant server would return `error: invalid_grant`. |
There was a problem hiding this comment.
Deviating from the standard OAuth2 error format (error, error_description) in favor of RFC 9457 breaks compatibility with standard OAuth2 client libraries, potentially causing client-side failures or improper error handling in integrated applications.
Collaborator
Author
There was a problem hiding this comment.
I will review it in other pr and align API codebase with documentation.
|
|
||
| Two are choices the specifications leave to the server: | ||
|
|
||
| - **Refresh tokens rotate on every use.** A successful refresh retires the token presented and returns a replacement in `refresh_token`, as RFC 6749 Section 6 permits and the OAuth2 Security Best Current Practice recommends. Store the new value; the old one stops working. Refresh tokens expire 30 days after they are issued, and rotation restarts that window. The authorization code flow returns a refresh token with every access token; the client credentials flow returns none (RFC 6749 Section 4.4.3). |
There was a problem hiding this comment.
Removing the /oauth2/revoke endpoint prevents clients from invalidating compromised or unused tokens (RFC 7009), extending the window of opportunity for attackers holding stolen access or refresh tokens until they naturally expire.
| Two behaviors do not conform to the specifications: | ||
|
|
||
| - **Errors use RFC 9457 problem+json, not RFC 6749 Section 5.2.** Failures return `application/problem+json` with `type`, `title`, `status`, and `instance`. There is no `error` or `error_description` field, so the standard codes (`invalid_grant`, `invalid_client`, `unsupported_grant_type`) never appear — branch on the HTTP status and `title` instead. A refresh token that is expired, already rotated, or unrecognized returns `400` with a `title` of `Refresh token has expired` or `Invalid refresh token`, where a conformant server would return `error: invalid_grant`. | ||
| - **`refresh_token` is not a registrable grant type.** RFC 7591 Section 2 lists it, but `/oauth2/register` accepts only `authorization_code` and `client_credentials` in `grantTypes`. Refreshing requires no registration: holding a refresh token issued to the client is the authorization. A consequence is that refresh capability cannot be disabled per client — every `authorization_code` grant returns a refresh token, so a client intended for a shared or public device cannot be registered without one. |
There was a problem hiding this comment.
Mandatory refresh_token for all authorization_code grants prevents clients on shared or public devices from opting out of long-lived session persistence, increasing risk of unauthorized access (RFC 6749 Section 4.1.4).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Updated docs with
refresh-tokengrant type.