TL;DR

  1. OAuth refresh token lifetimes range from minutes to years across different providers. Some limits restart with every refresh, others are fixed, and often the tenant’s administrator decides, not the vendor.

    Link to this findingSave as image (PNG, 1200 by 630 pixels)

  2. Only a few providers report the remaining refresh token lifetime in the token response, and they don’t agree on a field name.

    Link to this findingSave as image (PNG, 1200 by 630 pixels)

  3. An IETF draft adds the refresh token lifetime to the token response. It keeps invalid_grant as the only error and leaves rotation settings out.

    Link to this findingSave as image (PNG, 1200 by 630 pixels)

While integrating third-party OAuth providers into the Agentic Identity Broker, three things cost me the most. Refresh tokens expired without any announcement. When they did, the provider answered with the same invalid_grant it uses for every other cause. And some providers, Databricks in my case, let an administrator change how refresh tokens rotate, with side effects on token issuing and expiry. In October, lost third-party sessions were the broker’s most visible problem.

All three have the same cause. OAuth gives a provider no standard way to tell a client how long a refresh token lives or why it stopped working. So each vendor writes its limits into its documentation, returns them in a custom field it made up, or simply says nothing. Different limits and behaviours are fine with me, as long as a client can read them. An IETF draft proposes that for the token lifetime.

Why providers pick their own limits #

The specifications leave refresh token lifetimes open. The draft I discuss below sums up RFC 6749 like this: 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’”. The security best practice (RFC 9700) says that refresh tokens “SHOULD expire if the client has been inactive for some time” and puts the expiration time “at the discretion of the authorization server”.

Most providers bind the refresh token to the grant that the user gave the client and give it a lifetime of its own. Off-the-shelf identity products let the tenant’s administrator set that lifetime, usually per client application, so two integrations with the same provider can behave differently.

Idle and absolute limits each have a good reason to exist. An idle limit ends refresh tokens that nobody uses any more, as RFC 9700 asks. An absolute limit ends access that is still in use, which providers want, according to the draft, when access is “too sensitive to allow indefinite access (e.g. mail or health data)”. So I don’t question that providers set these limits. The trouble starts on the integrator’s side, where I have to look up each provider’s combination and hard-code it or work around it.

Refresh token lifetimes at 18 providers #

The table lists what each vendor documents as of November 2026. “Renewed by refreshing” means that a successful refresh starts the clock again, and “tenant” means that whoever operates or administers the tenant sets the limit.

ProviderRefresh token limitRenewed by refreshingSet byIn the token response
Airtable60 daysyesvendorrefresh_expires_in
Amazon Cognito30 days after sign-in by default, 60 minutes to 10 yearsnotenantno
Atlassian90 days of inactivityyesvendorno
Auth0idle 30 days by default, maximum up to 1 year or switched offidle yes, maximum notenantno
Box60 daysyesvendorno
Databricks7 days by default, 5 minutes to 90 daysonly with single-use tokenstenantno
GitHub Apps6 months, with expiring user tokens enabledyesvendorrefresh_token_expires_in
Google6 months without use, 7 days for apps in testingyesvendor, or the user with time-based accessno
Intuit QuickBooks100 days without use, 5 years in total100 days yes, 5 years novendorx_refresh_token_expires_in
Keycloaksession idle and session maximumidle yes, maximum notenantrefresh_expires_in
Linear30 daysyesvendorno
Microsoft Entra90 days by default, 24 hours for single-page apps and email one-time passcodesnot for single-page appsvendorno
Notion MCP180 days from authorizationnovendorno
Oktaunlimited by default, 7 days without useidle yestenantno
Salesforceuntil revoked by default, or idle, or fixeddepends on the policytenantno
Spotify6 months from authorizationnovendorno
Xero60 days without useyesvendorno
Zoom90 daysnew token per refresh, restart of the 90 days not statedvendorno

A “no” in the last column means that the linked documentation shows no such field. The table rests on documentation alone and not on tests, so please read it as a snapshot of vendor claims.

Where the vendor fixes the limit, it goes from 24 hours for single-page apps at Microsoft to 5 years at Intuit. Where the tenant sets it, the range is wider still: from 5 minutes at Databricks to 10 years at Cognito, and the default at Salesforce has no limit at all. The numbers also mean different things. At Linear or Box, a client that refreshes regularly keeps its connection for good. At Notion or Spotify, the same client loses it after 180 days or 6 months, however often it refreshed. At 6 of the 18, the vendor doesn’t decide the limit. Auth0, Cognito, Keycloak and Okta are identity products that other companies run, and at Databricks and Salesforce the customer’s administrator configures the policy per application. For these 6, the documentation only gives me the range of what I might meet in the wild.

Rotation settings change the rules per client #

Databricks is the example I ran into myself. An administrator can set a refresh token time-to-live (TTL) for each OAuth application, 10080 minutes or 7 days by default, and can turn on single-use refresh tokens, which is Databricks’ name for refresh token rotation. With rotation, the provider issues a new refresh token on every refresh and invalidates the old one. The API reference explains what that switch does to the first setting: “When single-use refresh tokens are enabled, this represents the TTL of an individual refresh token. If the refresh token is used before it expires, a new one is issued with a renewed individual TTL.” About a second setting, the absolute session lifetime, it says: “Effective only when the single-use refresh token feature is enabled.”

So with rotation on, the same number becomes a sliding limit, and a separate setting defines the absolute end, which with rotation off is simply the TTL. My client sees none of this. It gets a refresh token and finds out later which combination the administrator chose.

Rotation can also come with a reuse interval, also called grace period or leeway, in which the previous refresh token still works, so that a lost response doesn’t end the session. Every provider that offers this concept seems to size it differently: Okta 30 seconds by default, Atlassian 10 minutes, Linear and Xero 30 minutes, and Notion keeps the one previous token valid. Outside that interval, Notion treats a reused token as stolen and can revoke the whole grant. A client that runs more than one replica has to know these numbers, and they exist in documentation only as well.

One invalid_grant for every cause #

When a refresh token has ended, the client learns it through invalid_grant. RFC 6749 defines that code for a grant or refresh token that “is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client”. The providers add their own causes behind it. Atlassian returns it after the user changed their password. Microsoft documents a matrix of which password event revokes which kind of refresh token. Google invalidates the oldest token “without warning” once an account holds more than 100 for the same client.

I can’t tell these causes apart in the client, so I can’t tell my own user either. “Your access expired after 90 days” and “someone revoked this app” call for different messages, and my client only knows that the person has to log in again. Google is an exception for one case: when an administrator’s session policy ends the access, it adds an error_subtype to the response. In case you want to read more about the revocation side, see my field guide entry on consent and revocation.

Four vendors report the lifetime in their own fields #

Four vendors already return the remaining lifetime in the token response, and (of course) they use three different names for it:

VendorField in the token responseMeaning
GitHubrefresh_token_expires_inseconds until the refresh token expires, always 6 months
Airtablerefresh_expires_inseconds until the refresh token expires, 60 days expected
Keycloakrefresh_expires_inseconds until the refresh token expires, per its token response class
Intuitx_refresh_token_expires_inseconds left of the rolling 100 days
Intuitx_refresh_token_hard_expires_inseconds left of the 5 years, only with a request header

A known date lets my client plan ahead. I can ask users to reauthorize the next time they are around, or contact them out of band, well before the connection ends and a business process breaks. I can also refresh idle connections just before the provider would end them, instead of running a generic cron job. Planning ahead currently still needs a code path per provider.

What the IETF draft adds #

OAuth 2.0 Refresh Token and Authorization Expiration by Nick Watson of Google started as an individual draft in June 2025. The OAuth working group adopted it in December 2025, and revision 03 is from 6 July 2026. It defines two parameters for the token response:

  • refresh_token_timeout is the “time in seconds that the refresh token may be held by the client without exchanging”, which is the idle limit.
  • authorization_expires_in is the “lifetime in seconds of the user’s authorization for the scopes contained in the issued or presented refresh token”, which is the absolute limit.

A provider with a 7-day idle limit and a user who granted access for 10 days would answer like this:

File: token-response.json
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "refresh_token_timeout": 604800,
  "authorization_expires_in": 864000
}

The two parameters match the two clocks from the table above. Linear could send only the first, Spotify only the second and Intuit both. An authorization server can announce its support in its metadata with refresh_token_expiration_types_supported, and the draft extends token introspection so that a client can ask about a refresh token it already holds. For rotating tokens, the draft says that the duration can now “be communicated as part of the API rather than relying on documentation”.

What I still miss in the draft # Updated 18 Nov

I consider the draft a good start, but it leaves three things open.

The error stays as it is. According to the draft, the “existing invalid_grant error code already explicitly covers token expiration and should be sufficient”. For a planned expiry I agree, because the client knew the date. For every other cause, the client is where it was. I’d like to see a machine-readable reason next to invalid_grant, along the lines of Google’s error_subtype, that separates expired, revoked and rotated-out tokens. RFC 6749 does allow an error_description, but it’s optional, human-readable text meant “to assist the client developer”. Each provider words it differently and can change it at any time, so a client that branches on it is back to hard-coding per provider.

Rotation settings are missing too. Whether refresh tokens rotate and how long the previous one stays valid could be two more fields in the authorization server metadata. For a client with several replicas, they matter as much as the lifetime.

My biggest doubt is about adoption. The draft currently targets Informational as the intended status, and it’s marked as optional. Without that field, a missing parameter can mean that the token has no limit or that the provider doesn’t support the draft, and the draft tells clients to handle both in the same way. GitHub, Airtable, Keycloak and Intuit already ship field names that their clients might depend on, and I see little that would make them add a second set. What could help is a profile that requires the parameters, such as the MCP Authorization specification.

What an integrator can do today #

Until providers report their limits, the limits have to live in the client. This is what I’d do in an integration today, and the vendor documentation backs most of it:

  • Treat invalid_grant as final, discard the refresh token and start a new authorization instead of retrying.
  • Allow only one refresh per grant at a time, across all replicas, and store the new refresh token together with the new access token before using either.
  • Read the vendor’s own expiry field where one exists, and read it from every response, because the value can change from one refresh to the next.
  • Refresh connections that nobody uses before a known idle limit ends them.
  • Keep the limits in configuration per provider, per tenant and per client application. With admin-set policies, two customers of the same vendor, or two applications of the same customer, can behave differently.
  • Tell the user the date where there is one, so they can reconnect before a job fails.

For MCP servers, I started to collect what vendors state about refresh token rotation in the MCP auth atlas of Letsauth Lab, which I maintain and introduced in Measuring How MCP Servers Authorize Agents. If you know how a provider expires or rotates its refresh tokens and the table above has it wrong, I’d like to hear about it. And if you miss the same things in the draft as I do, its issue tracker is the place to say so.

Updates

  1. Added why error_description can’t replace a machine-readable reason next to invalid_grant. See the change
  2. Published
Licence
CC BY 4.0
ID
jb-refresh-token-lifetime

Cite this

Citation format

Jan Brennenstuhl. “Nobody Tells You When an OAuth Refresh Token Expires.” Brennenstuhl on Security, 17 November 2026. https://www.janbrennenstuhl.eu/refresh-token-lifetime/

Brennenstuhl, J. (2026, November 17). Nobody Tells You When an OAuth Refresh Token Expires. Brennenstuhl on Security. https://www.janbrennenstuhl.eu/refresh-token-lifetime/

@online{brennenstuhl2026nobody,
  author = {Brennenstuhl, Jan},
  title = {Nobody Tells You When an OAuth Refresh Token Expires},
  date = {2026-11-17},
  organization = {Brennenstuhl on Security},
  url = {https://www.janbrennenstuhl.eu/refresh-token-lifetime/}
}

Markdown Send a correction