OAuth 2.0 Refresh Token and Authorization Expiration

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 31 August 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

RFC6749 defines the OAuth 2.0 protocol, part of which is the ability for a client to receive a refresh token that may be repeatedly exchanged for more access tokens. OAuth 2.0 does not contain any normative language around expiration or lack thereof for refresh tokens, mentioning only that they are "typically long-lasting".¶

In the years since the publication of OAuth 2.0, in response to changing security and privacy landscapes, many authorization servers have begun to issue shorter-lived refresh tokens for two main reasons:¶

• The authorization server or user may decide that the access being granted is too sensitive to allow indefinite access (e.g. mail or health data).¶

• The authorization server enforces a maximum duration that refresh tokens may be held without being exchanged on the token endpoint.¶

Clients may wish to implement special handling for expiring refresh tokens. For example, if the user has granted expiring access, the client may notify the user that they will need to reauthorize access before a certain date to avoid interruption of service.¶

2. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. Terminology

"Resource owner" and "user" may be used interchangeably to refer to the entity capable of granting access to a protected resource.¶

"Client", "application", and "relying party" may be used interchangeably to refer to the application making protected resource requests on behalf of the resource owner and with its authorization.¶

4. Concepts

There are two mechanisms that can affect refresh token expiration.¶

5. Refresh token expiration

The refresh token MUST NOT expire later than the user authorization expires. It MAY expire earlier if the authorization server also enforces a maximum duration between refresh token exchanges.¶

If the user renews their authorization, the authorization server SHOULD update the expiration time of existing refresh tokens if their lifetime was truncated due to user authorization expiration. The authorization server MUST NOT accept expired refresh tokens for any purpose, even if it has no way to update the expiration time of existing refresh tokens.¶

Access tokens MUST NOT expire later than the user authorization expires. If the user renews their authorization, the authorization server MAY update the expiration time of existing access tokens if possible. Resource servers MUST NOT accept expired access tokens for any purpose, even if the authorization server has no way to update the expiration time of existing access tokens.¶

6. Token endpoint response

This specification introduces two new response parameters.¶

refresh_token_timeout
      The time in seconds that the refresh token may be held by the client
      without exchanging. For example, the value 604800 denotes that the
      refresh token will expire in one week from the time the response was
      generated. This value SHALL NOT exceed the value in
      authorization_expires_in.

authorization_expires_in
      The lifetime in seconds of the user's authorization for the scopes
      contained in the issued or presented refresh token. For example, the
      value 2629800 denotes that the authorization will expire in one month
      from the time the response was generated. This value MAY exceed that
      of refresh_token_timeout.

refresh_token_timeout: 604800  // 7 days
authorization_expires_in: 2592000  // 30 days

refresh_token_timeout: 604800  // 7 days
authorization_expires_in: 1987200  // 23 days

refresh_token_timeout: 172800  // 2 days
authorization_expires_in: 172800  // 2 days

error: invalid_grant
error_description: "expired refresh token"

7. Update to Authorization Server Metadata

Support for the expiring refresh tokens SHOULD be declared in the OAuth 2.0 Authorization Server Metadata [RFC8414] with the following metadata:¶

refresh_token_expiration_types_supported
    OPTIONAL. JSON array of supported expiration types. The possible values
    are "authorization" and "credential".

If the authorization server omits expiration time response fields to indicate indefinite validity, it MUST declare refresh_token_expiration_types_supported in its metadata to indicate to the client that it's aware of this spec.¶

8. User Experience Considerations

While clients must be able to gracefully handle tokens' expiring at any time, the user experience may suffer if there's an unintended interruption of service. This degradation of experience would most likely be felt by users of clients running in the background, such as task or travel management apps that rely on access to a user's calendar or inbox.¶

If an application recognizes that its access is nearing expiration, it can proactively prompt the user for reauthorization next time they're "in the loop" (e.g. using a parameter like prompt=consent from [OpenID]), or even communicate to the user out of band that their granted access is expiring.¶

Another option an authorization server could provide to the user is a management surface where the user can go proactively extend the lifetime of their own grant, which would update the lifetime of the client's refresh token(s) in place. The client would discover the extended expiration on its next refresh token grant request.¶

9. Security Considerations

While it is possible to allow refresh token expiration to exceed that of user authorization expiration if the authorization server checks both timestamps when validating a refresh token, this is a potentially dangerous source of bugs in systems with complicated user authorization models. By requiring refresh tokens to expire no later than user authorization expires, there is less risk of bugs that accidentally provide data access to the client beyond the term of the user's authorization.¶

Authorization servers implementing token rotation on every refresh [RFC 9700] Sec 4.14 may wish to enforce a maximum duration that a refresh token may be held without rotation, and this specification allows that duration to be communicated as part of the API rather than relying on documentation.¶

Clients may wish to maintain multiple refresh tokens with different access in order to separate different lifetimes across different scopes. For example, a short-lived token to access financial data and a long-lived token to access basic user info. There is a tradeoff here, both in complexity of token management and also in increased friction for the user to authorize multiple tokens.¶

10. Privacy Considerations

Allowing users to time-limit their authorization is a privacy improvement. While this was already doable in regular OAuth implementations, the potential interruption of service for the user may have discouraged implementation of the feature. This specification provides a standardized way to mitigate that concern and should lead to greater adoption of time-limited authorization.¶

11. IANA Considerations

12. References

Acknowledgments

TODO acknowledge.¶

Author's Address