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.

Two types of tokens:

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 user revoked your app's access or the refresh token expired. Clear stored tokens and send the user through OAuth authorization again.

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