OAuth Token Management: A Practical Guide

On this page

1. What token management covers
2. Modelling connections
3. Refresh strategies
4. Concurrency
5. Provider differences
6. Detecting broken connections
7. Reauthorization
8. Cleanup
9. Metrics worth tracking
10. Where Pathfix fits
11. Frequently asked questions

Getting a token is the easy part of OAuth. The authorization flow runs once per connection. Token management runs for as long as the connection exists, for every customer, across every provider you support.

This guide is about that second part: the operational work of keeping thousands of OAuth connections usable over months and years.

What token management covers#

For each connected account, your system needs to:

• Store the access token, refresh token, expiry, granted scopes and provider details.
• Associate the connection with the correct customer, user and tenant.
• Supply a valid access token whenever your code calls the provider's API.
• Refresh tokens before or when they expire.
• Detect connections that can no longer be refreshed.
• Prompt the right user to reconnect.
• Revoke and delete credentials when a connection is removed.

None of these is hard alone. Together, across many providers, they become a system that needs design, monitoring and ongoing maintenance.

Modelling connections#

Start with a clear data model. A connection record typically includes:

Store granted scopes as returned by the provider, not as requested. Users can sometimes deselect permissions during consent.

Refresh strategies#

There are two common approaches.

Refresh on demand. Before each API call, check the expiry. If the token is expired or close to expiring, refresh first. This is simple and only refreshes connections that are actually used.

Refresh proactively. A scheduled job refreshes tokens shortly before they expire. This keeps tokens ready for latency-sensitive calls, and detects broken connections earlier, but makes refresh calls for connections that might not be used.

Many systems combine them: refresh on demand, plus a periodic job that exercises connections that haven't been used recently so problems surface before a customer notices.

Also handle the case where a token is rejected before its recorded expiry. Providers can revoke tokens early. A 401 from the API should trigger one refresh attempt, then a retry of the request.

Concurrency#

At scale, the same connection is often used by several workers at once. If two of them notice an expired token and refresh simultaneously, and the provider rotates refresh tokens, one refresh will invalidate the other's token.

Use a per-connection lock or a single-flight mechanism so only one refresh happens at a time, and other callers wait for its result. Persist the new tokens before releasing the lock.

Provider differences#

Token behaviour isn't standard across providers. Differences you'll meet include:

• Whether refresh tokens are issued at all, and what scope or parameter is needed to get one.
• Whether refresh tokens rotate on each use.
• Whether refresh tokens expire after a fixed time or after inactivity.
• How many active refresh tokens a user can have for one app.
• Which error codes mean "retry" and which mean "reconnect".
• Whether a password change or admin policy change revokes existing tokens.

Keep this behaviour in per-provider configuration rather than scattered through application code.

Detecting broken connections#

A connection can break silently. The user revokes access in the provider's settings. An administrator removes the app. A refresh token expires after months without use.

Track a status for each connection and update it when refreshes or API calls fail permanently. Then make the status visible:

• In your product, next to the integration, with a "Reconnect" action.
• To the user who authorized it, by email or in-app notice.
• To your team, as an aggregate metric by provider, so you notice when a provider change breaks many connections at once.

Reauthorization#

When a connection needs reauthorization, send the user through the authorization flow again and update the existing connection record rather than creating a new one. That preserves the connection ID your other data references.

Check that the reconnected external account matches the original. If a user reconnects with a different account, decide whether that's allowed and what happens to data synchronized from the old account.

Cleanup#

When a customer disconnects or leaves:

1. Revoke tokens at the provider if a revocation endpoint exists.
2. Delete stored tokens.
3. Cancel related webhook subscriptions and scheduled jobs.
4. Keep only the audit records you need.

Metrics worth tracking#

• Active connections by provider.
• Refresh success rate by provider.
• Connections entering "needs reauthorization" per day.
• Time from broken connection to successful reconnect.
• API calls failing with authorization errors.

A sudden jump in any of these for one provider usually means the provider changed something.

Where Pathfix fits#

Token management is the part of OAuth that never finishes. Pathfix OAuth handles token storage, token refresh and authenticated API passthrough across 350+ providers, with your own OAuth apps and credentials. Your application calls provider APIs through Pathfix and keeps ownership of which endpoints to call and what to do with the data.

Read the documentation for details on connections and API passthrough.

Frequently asked questions#

How often should I refresh tokens?#

Only when needed: on demand near expiry, or shortly before expiry if you refresh proactively. Unnecessary refreshes can hit provider rate limits.

What if a provider doesn't issue refresh tokens?#

The user will need to reauthorize when the access token expires, unless the provider offers another mechanism. Design the reconnect experience with that in mind.

Should I delete connections that haven't been used for a long time?#

Consider it. Unused connections still hold credentials. A retention policy, communicated to users, reduces risk.