OAuth Token Refresh

Access tokens expire after 1 hour. This guide shows you how to automatically refresh them to keep your integration running smoothly.

Why Do Tokens Expire?

Security. Short-lived access tokens limit damage if they're stolen. Even if someone intercepts your access token, it only works for 1 hour.

OAuth 2.0 encourages short-lived access tokens and long-lived refresh tokens, and leaves the lifetimes to each implementation. The reasons:

• Token compromise: a short-lived access token limits how long an attacker can use a stolen one.
• Least privilege: access is granted for the shortest time it is needed.
• Rotation: short lifetimes mean tokens are replaced often, which makes a stolen one harder to misuse.
• Audit and revoke: short-lived tokens are easier to audit, and to revoke one at a time.
• Refresh tokens: a new access token is obtained with a refresh token, and only the app the refresh token was issued to can use it: the refresh request carries that app's client credentials.

The OAuth 2.0 Security Best Current Practice and oauth.com's guide to refreshing an access token cover the background.

Two types of tokens:

How Long a Refresh Token Lasts

A refresh token has no fixed expiry. It works once: each refresh returns a new access token and a new refresh token, and revokes the old pair straight away.

A refresh token stops working when:

• it has been used to refresh, even if your app never received the response;
• your app revokes it, or the access token it was issued with, at POST /oauth/revoke;
• the user removes your app's access in their DoorFlow settings;
• DoorFlow support revokes all of the user's tokens;
• the user, or your OAuth application, is deleted.

Any of these makes the next refresh fail with invalid_grant, and the user has to authorize your app again.

Think of it like a hotel key card:

• Access token = Your room key (expires when you check out)
• Refresh token = Your ID at the front desk (get a new room key anytime)

What Happens When Tokens Expire

When your access token expires, the API returns 401 Unauthorized. This is your signal to refresh.

The Token Refresh Flow

Here's the complete process when a token expires:

How to Refresh a Token

Request:

curl -X POST "https://api.doorflow.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502003d8f9a7b2c1e4d5f6g7h8i9j0k...",
  "scope": "account.person",
  "created_at": 1704070800
}

Critical: You receive BOTH:

• New access token - Use this for API calls
• New refresh token - Store this and use it for the next refresh

The old refresh token is now invalid. Always use the newest refresh token.

Implementation Approach 1: Reactive Refresh

Strategy: Wait for 401, then refresh and retry.

Implementation Approach 2: Proactive Refresh

Strategy: Check expiration time before making calls. Refresh early if needed.

How to track expiration:

When you store tokens, also calculate and store the expiration time:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def502003d8f9a7b2c1e4d5f6g7h8i9j0k...",
  "expires_at": 1704074400
}

When Token Refresh Fails

Not all refresh attempts succeed. Here's how to handle failures:

Common errors:

Most common: invalid_grant means the refresh token was already used, or was revoked (see How Long a Refresh Token Lasts). Retrying cannot help. Clear stored tokens and send the user through OAuth authorization again.

Things to Watch Out For

Because a refresh token works once, how your app handles a refresh decides whether it keeps its access:

1. Replace tokens together. When a refresh succeeds, store the new access token and the new refresh token in one atomic write. The old pair no longer works.
2. Refresh one at a time. Two refreshes with the same refresh token cannot both succeed: DoorFlow answers the second with invalid_grant. Make sure only one request per user refreshes at once, and let the others wait for its result.
3. Handle errors. Check that a refresh response is what you expect before you use it, and log and alert on failures so someone can step in.
4. Set timeouts. Give the refresh request a timeout so a hung request does not block your app. If a refresh times out, the old refresh token may already be revoked: the next attempt then fails with invalid_grant.
5. Validate new tokens before use. Check the new tokens' format and values before they replace the old ones.
6. Retry with exponential backoff, but not on invalid_grant. Retry a refresh that failed on a network error or a 5xx response, backing off each time so you do not overwhelm the token endpoint. An invalid_grant is final.
7. Log and monitor token operations, never token values. Log each refresh and its outcome, and alert on errors. Never write an access or refresh token to a log.
8. Have a manual fallback. Give support a way to reconnect a user by hand when automated refresh fails, as a last resort.

Storing Tokens Securely

What to store:

{
  "user_id": 12345,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "ENCRYPTED:def502003d8f9a7b2c1e4d5f6g7h8i9j0k...",
  "expires_at": 1704074400,
  "scope": "account.person account.channel.readonly"
}

Critical: Refresh tokens are long-lived and powerful. If someone steals a refresh token, they can access the API indefinitely. Always encrypt them.

Testing Your Implementation

Complete Flow Example

Here's everything together - from initial OAuth through token refresh:

Quick Decision Guide

Which refresh strategy should I use?

When do I need to re-authorize the user?

Only when refresh token is invalid:

• User revoked your app's access
• OAuth app credentials changed
• OAuth app was deleted
• Refresh token manually deleted

Regular expiration of access tokens does NOT require re-authorization.

Common Mistakes

1. Not storing the new refresh token

Each refresh gives you a NEW refresh token. The old one is invalid.

2. Not handling refresh failures

Refresh can fail. Always have a fallback to re-authorize.

3. Logging tokens

Never log access or refresh tokens. Use [REDACTED] in logs.

4. Storing tokens in localStorage (web apps)

Use secure, httpOnly cookies or server-side sessions. localStorage is vulnerable to XSS attacks.

5. Sharing tokens between users

Each user needs their own tokens. Never reuse tokens across different users.

Quick Reference

Refresh a token:

POST https://api.doorflow.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=YOUR_REFRESH_TOKEN
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Next Steps

Now that you understand token refresh:

• [OAuth Authorization Flow] - See where refresh tokens come from
• [Choosing the Right Scopes] - Select appropriate permissions
• [Error Handling] - Handle all API error scenarios
• [Common Workflows] - See complete integration examples