Refresh Token

A refresh token is designed to have a significantly longer lifespan than an access token. While an access token may expire in minutes or hours, a refresh token can be valid for days, weeks, or even months. This longevity is the core mechanism that enables seamless, long-term API access without forcing the user through repeated login prompts. The token's extended validity is managed and can be revoked by the authorization server at any time.

A refresh token is not requested independently. It is issued by the authorization server in the same response that delivers the initial access token, but only for specific OAuth 2.0 grant flows. The primary flows that support refresh tokens are:

• Authorization Code Flow (with PKCE)
• Resource Owner Password Credentials Flow (now discouraged)
• Device Authorization Flow It is explicitly not issued in the Client Credentials Flow, as that flow represents machine-to-machine communication without a user context to maintain.

The sole, defined purpose of a refresh token is to be presented to the authorization server's token endpoint to request a fresh access token. This request is a background, server-to-server operation that does not involve the end-user. The client application sends the refresh token along with its client authentication credentials. Upon successful validation, the authorization server returns a new access token (and optionally a new refresh token). This cycle continues until the refresh token expires or is revoked.

Due to its long lifespan and powerful ability to grant new access tokens, a refresh token is considered a highly sensitive secret. Security best practices mandate that it must be stored securely by the client application that receives it. For web applications, this means storing it in an HTTP-only, secure cookie or a server-side session store, never in browser local storage where it could be exposed to cross-site scripting (XSS) attacks. Native mobile apps should use platform-specific secure storage like the iOS Keychain or Android Keystore.

A refresh token is not an all-powerful key. It is tightly bound to the client ID that originally requested it. The authorization server validates this binding upon every refresh request. Crucially, refresh tokens are revocable at any time. Revocation can be triggered by:

• The user explicitly revoking application consent.
• An administrator action for security reasons.
• The authorization server detecting anomalous behavior. Revocation is typically performed via a call to the token revocation endpoint (RFC 7009), which immediately invalidates the token and cascades to invalidate any access tokens derived from it.

The refresh token pattern is a direct security trade-off. It allows access tokens to have very short lifetimes (e.g., 5-15 minutes), which limits the damage window if a token is leaked or stolen. Without refresh tokens, short-lived access tokens would create a poor user experience. With them, security is improved without sacrificing usability. This architecture aligns with the principle of least privilege and defense in depth, ensuring that a compromised access token has limited utility while maintaining a secure mechanism for sustained access.

An access token is a short-lived credential issued by an authorization server that grants a client application permission to access specific protected resources on behalf of a user. It is the primary credential presented to a resource server (API).

• Lifespan: Typically expires in minutes or hours (e.g., 1 hour).
• Contents: Encodes scopes, user identity, client identity, and an expiration timestamp.
• Bearer Token: Most commonly implemented as a JWT (JSON Web Token), allowing the resource server to validate it without a call back to the authorization server.
• Security: Its short lifetime limits the window of opportunity if the token is compromised.

The Authorization Code flow is the standard OAuth 2.0 grant type for server-side web applications and is the primary flow where refresh tokens are issued. It involves a multi-step handshake designed to keep tokens secure.

• Steps: 1) User authorization redirect, 2) Exchange of an authorization code for tokens.
• Security: The access token is delivered directly to the client's backend, never exposed to the user's browser.
• PKCE Extension: Proof Key for Code Exchange (PKCE) is a mandatory extension for mobile and single-page apps to prevent authorization code interception attacks.
• Token Issuance: Upon successful code exchange, the authorization server returns both an access token and a refresh token.

Token introspection is an OAuth 2.0 extension (RFC 7662) that allows a resource server to query the authorization server to validate an access token and retrieve its meta-information. This is a critical mechanism for secure API gateways.

• Endpoint: The resource server calls a dedicated /introspect endpoint.
• Response: Returns a JSON object indicating if the token is active, along with its scopes, client ID, username, and expiration.
• Use Case: Essential when the resource server cannot validate token signatures directly (e.g., with opaque tokens).
• Contrast with Refresh: Introspection validates an existing token; a refresh request obtains a new token.

Token revocation is the process of invalidating an access or refresh token before its natural expiration. This is a critical security control for responding to incidents or user logout events.

• Endpoint: Achieved by calling the OAuth 2.0 /revoke endpoint (RFC 7009).
• Immediate Effect: Revoked tokens become unusable immediately, unlike waiting for expiration.
• Refresh Token Impact: Revoking a refresh token also invalidates any access tokens derived from it.
• Security Posture: A mandatory capability for systems adhering to the OAuth 2.0 Threat Model (RFC 6819) to mitigate token theft.

The Client Credentials flow is an OAuth 2.0 grant type used for machine-to-machine (M2M) communication where an application accesses its own resources, not on behalf of a user. Refresh tokens are not used in this flow.

• Authentication: The client authenticates with its own client_id and client_secret.
• Token Use: The issued access token represents the application itself.
• No User Context: Since there is no user authorization, there is no long-lived session to maintain, eliminating the need for a refresh token.
• Contrast: Highlights that refresh tokens are specifically for maintaining user-delegated authorization across sessions.

A scope is an OAuth 2.0 mechanism that limits an application's access to a user's resources. Scopes are central to the principle of least privilege and are embedded within both access and refresh tokens.

• Definition: A space-separated list of case-sensitive strings (e.g., read:contacts api:write).
• Authorization: The user consents to specific scopes during the initial authorization request.
• Token Binding: The issued access token is only valid for the granted scopes. A refresh token is typically bound to the same set of scopes.
• Security: Prevents an application with a refresh token from escalating its privileges; refreshed access tokens cannot have broader scopes than the original grant.