File: C:/Users/fred/.codex/.tmp/plugins/plugins/zoom/skills/oauth/concepts/token-lifecycle.md
# Token Lifecycle
Understanding how Zoom OAuth tokens are created, expire, refresh, and revoke is critical for building reliable integrations.
## Token Types
### Access Token
- **Purpose:** Authenticate API requests
- **Lifetime:** 1 hour (all OAuth flows)
- **Usage:** `Authorization: Bearer {access_token}` header
- **Format:** Opaque string (not JWT)
### Refresh Token
- **Purpose:** Obtain new access tokens without user re-authorization
- **Lifetime:** Varies by flow/account/app configuration; ~90 days is common for some user-based flows (treat as changeable behavior)
- **Availability:** S2S OAuth and Chatbot do NOT have refresh tokens
- **Rotation:** Each refresh returns a NEW refresh token (old one becomes invalid)
### Authorization Code
- **Purpose:** Temporary code exchanged for access token
- **Lifetime:** 5 minutes
- **Usage:** User OAuth and Device Flow only
- **One-time use:** Code becomes invalid after exchange
---
## Expiration Summary
| Flow | Access Token | Refresh Token | Strategy |
|------|--------------|---------------|----------|
| **S2S OAuth** | 1 hour | None | Request new token before expiration |
| **User OAuth** | 1 hour | ~90 days (commonly) | Use refresh token to get new access token |
| **Device Flow** | 1 hour | ~90 days (commonly) | Use refresh token to get new access token |
| **Chatbot** | 1 hour | None | Request new token before expiration |
---
## S2S OAuth & Chatbot Token Lifecycle
### Timeline
```
┌────────────────────────────────────────────────────┐
│ │
│ Token Request │
│ │ │
│ v │
│ [ Access Token Valid ] │
│ │
│ ├───────────────────── 1 hour ──────────────────┤ │
│ │
│ Token │
│ Expires │
│ │ │
│ v │
│ Request New Token ────────────────> [ New Access Token Valid ]
│ │
└────────────────────────────────────────────────────┘
```
### Strategy: Cache with TTL
```javascript
const redis = require('redis');
const client = redis.createClient();
const getToken = async () => {
// Check cache first
let token = await client.get('zoom_access_token');
if (!token) {
// Request new token
const response = await axios.post('https://zoom.us/oauth/token', ...);
const { access_token, expires_in } = response.data;
// Cache with TTL (10 second buffer before actual expiration)
await client.setex('zoom_access_token', expires_in - 10, access_token);
token = access_token;
}
return token;
};
```
**Key Points:**
- ✅ Cache token in Redis with TTL matching expiration
- ✅ Use 10-second buffer to prevent race conditions
- ✅ Single token shared across all requests
- ❌ Do NOT request new token on every API call
- ❌ Do NOT try to "refresh" (no refresh token exists)
---
## User OAuth & Device Flow Token Lifecycle
### Timeline
```
┌────────────────────────────────────────────────────────────────────┐
│ │
│ User Authorizes │
│ │ │
│ v │
│ [ Access Token Valid ] │
│ [ Refresh Token Valid ]────────────────────────────────────────┐ │
│ │ │
│ ├───────────── 1 hour ────────────┤ │ │
│ │ │
│ Access Token Expires │ │
│ │ │ │
│ v │ │
│ Refresh Request ──────────> [ New Access Token Valid ] │ │
│ [ New Refresh Token Valid ]────┐ │ │
│ │ │ │
│ ├───────────── 1 hour ────────────┤ │ │ │
│ │ │ │
│ Access Token Expires │ │ │
│ │ │ │ │
│ v │ │ │
│ Refresh Request ──────────> [ New Access Token Valid ] │ │ │
│ [ New Refresh Token Valid ] │ │ │
│ │ │ │
│ ... Continue refreshing up to ~90 days (commonly) ... │ │ │
│ │ │ │
│ ├──────────────────────── ~90 days (commonly) ───────────┤ │ │
│ │ │
│ Refresh Token Expires │ │
│ │ │ │
│ v │ │
│ User Must Re-Authorize (restart OAuth flow) │ │
│ │
└────────────────────────────────────────────────────────────────────┘
```
### Strategy: Auto-Refresh Middleware
```javascript
const tokenMiddleware = async (req, res, next) => {
const userId = req.session.userId;
// Get user's tokens from database
let { access_token, refresh_token, token_expiry } = await getUserTokens(userId);
// Check if access token is expired or will expire soon (5 minute buffer)
const now = Date.now();
const expiresIn = token_expiry - now;
if (expiresIn < 300000) { // Less than 5 minutes remaining
// Refresh the token
const response = await axios.post(
'https://zoom.us/oauth/token',
qs.stringify({
grant_type: 'refresh_token',
refresh_token: refresh_token
}),
{
headers: {
'Authorization': `Basic ${Buffer.from(
`${CLIENT_ID}:${CLIENT_SECRET}`
).toString('base64')}`,
'Content-Type': 'application/x-www-form-urlencoded'
}
}
);
const { access_token: new_access_token, refresh_token: new_refresh_token, expires_in } = response.data;
// CRITICAL: Update BOTH tokens in database
await updateUserTokens(userId, {
access_token: new_access_token,
refresh_token: new_refresh_token, // NEW refresh token
token_expiry: now + (expires_in * 1000)
});
access_token = new_access_token;
}
// Attach token to request
req.zoomToken = access_token;
next();
};
```
**Key Points:**
- ✅ Refresh BEFORE token expires (5-minute buffer recommended)
- ✅ **ALWAYS save the NEW refresh token** (old one becomes invalid)
- ✅ Store tokens per user in database
- ✅ Encrypt tokens at rest (AES-256 minimum)
- ❌ Do NOT reuse old refresh token after refresh
- ❌ Do NOT wait for API 401 errors to trigger refresh
---
## Refresh Token Rotation
**CRITICAL:** Zoom rotates refresh tokens on every refresh.
### What Happens During Refresh
```
Before Refresh:
access_token: "abc123" (expired)
refresh_token: "xyz789" (valid)
Request:
POST /oauth/token
grant_type=refresh_token
refresh_token=xyz789
Response:
{
"access_token": "def456", // NEW access token
"refresh_token": "uvw012", // NEW refresh token
"expires_in": 3600
}
After Refresh:
access_token: "def456" (valid for 1 hour)
refresh_token: "uvw012" (lifetime varies; ~90 days is common)
OLD refresh_token "xyz789" is NOW INVALID
```
### Common Mistake
```javascript
// ❌ WRONG: Not saving new refresh token
const response = await refreshToken(old_refresh_token);
const { access_token } = response.data; // Only saving access token
await updateUserTokens(userId, { access_token }); // Refresh token not updated!
// Next refresh will fail with error 4735 "Invalid refresh token"
```
```javascript
// ✅ CORRECT: Saving both tokens
const response = await refreshToken(old_refresh_token);
const { access_token, refresh_token } = response.data;
await updateUserTokens(userId, {
access_token,
refresh_token // MUST save new refresh token
});
```
---
## Authorization Code Expiration
**Lifetime:** 5 minutes
### Timeline
```
User Clicks "Allow"
│
v
Authorization Code Issued (expires in 5 minutes)
│
│ ← Exchange code for token within 5 minutes
v
[ Access Token + Refresh Token ]
If code not exchanged within 5 minutes:
→ Error 4733 "Invalid authorization code"
→ User must re-authorize
```
### Implementation
```javascript
app.get('/callback', async (req, res) => {
const { code } = req.query;
try {
// Exchange code for token IMMEDIATELY
const response = await axios.post('https://zoom.us/oauth/token', {
grant_type: 'authorization_code',
code: code,
redirect_uri: process.env.REDIRECT_URI
}, ...);
// Store tokens
await saveTokens(response.data);
} catch (error) {
if (error.response?.data?.error === 'invalid_grant') {
// Code expired (4733) or already used
res.send('Authorization code expired. Please re-authorize.');
}
}
});
```
**Key Points:**
- ✅ Exchange authorization code **immediately** upon receiving it
- ✅ Authorization codes are one-time use
- ❌ Do NOT cache or store authorization codes
- ❌ Do NOT delay token exchange
---
## Token Revocation
### When Tokens Are Revoked
1. **User re-authorizes your app:**
- All previous tokens for that user become invalid
- New tokens are issued
2. **User removes your app:**
- All tokens for that user become invalid
- User must re-authorize to grant access again
3. **Explicit revocation:**
- Your app calls `https://zoom.us/oauth/revoke` endpoint
- Tokens become invalid immediately
4. **Refresh token expires (lifetime varies):**
- Can no longer refresh
- User must re-authorize
### Revoke Token API
```javascript
const revokeToken = async (access_token) => {
await axios.post(
'https://zoom.us/oauth/revoke',
qs.stringify({
token: access_token
}),
{
headers: {
'Authorization': `Basic ${Buffer.from(
`${CLIENT_ID}:${CLIENT_SECRET}`
).toString('base64')}`,
'Content-Type': 'application/x-www-form-urlencoded'
}
}
);
// Token is now revoked
// Delete from database
await deleteUserTokens(userId);
};
```
**What Gets Revoked:**
- Access token becomes invalid immediately
- Refresh token becomes invalid immediately
- All API requests with revoked token return 401
---
## Error Codes
| Code | Error | Meaning | Action |
|------|-------|---------|--------|
| **4733** | Invalid authorization code | Code expired (5 min) or already used | User must re-authorize |
| **4735** | Invalid refresh token | Refresh token expired or rotated | User must re-authorize |
| **4741** | Token has been revoked | Token was explicitly revoked | User must re-authorize |
| **401** | Unauthorized | Access token expired or invalid | Refresh token (if available) or re-authorize |
---
## Best Practices
### 1. Cache S2S Tokens
```javascript
// ✅ Cache in Redis with TTL
await redis.setex('zoom_token', expires_in - 10, access_token);
```
```javascript
// ❌ Request new token on every API call
const token = await getToken(); // Every time? No!
await makeAPIRequest(token);
```
### 2. Refresh BEFORE Expiration
```javascript
// ✅ Refresh with buffer (5 minutes before expiry)
if (expiresIn < 300000) {
await refreshToken();
}
```
```javascript
// ❌ Wait for 401 error
try {
await makeAPIRequest(token);
} catch (err) {
if (err.status === 401) {
await refreshToken(); // Too late!
}
}
```
### 3. Always Save New Refresh Token
```javascript
// ✅ Update both tokens
const { access_token, refresh_token } = await refresh();
await saveTokens({ access_token, refresh_token });
```
```javascript
// ❌ Only save access token
const { access_token } = await refresh();
await saveTokens({ access_token }); // Refresh token not saved!
```
### 4. Encrypt Tokens at Rest
```javascript
// ✅ Encrypt before storing
const encrypted = encrypt(access_token, CIPHER_KEY);
await db.query('UPDATE users SET token = ? WHERE id = ?', [encrypted, userId]);
```
```javascript
// ❌ Store in plain text
await db.query('UPDATE users SET token = ? WHERE id = ?', [access_token, userId]);
```
### 5. Handle Revocation Gracefully
```javascript
// ✅ Detect revoked tokens and prompt re-auth
if (error.code === 4741) {
await deleteUserTokens(userId);
res.redirect('/auth'); // Re-authorize
}
```
---
## Debugging Token Issues
### Symptom: "Token expired" immediately after getting it
**Cause:** Server clock is incorrect
**Solution:**
```bash
# Sync server time
sudo ntpdate -s time.nist.gov
```
### Symptom: Refresh fails with "Invalid refresh token" (4735)
**Cause:** Using old refresh token after it was rotated
**Solution:**
- Check database: Are you saving the NEW refresh token?
- Check code: Are you updating BOTH access_token AND refresh_token?
### Symptom: Authorization code fails with "Invalid grant" (4733)
**Cause:** Code expired (5 minutes passed) or already used
**Solution:**
- Exchange code immediately in callback
- Codes are one-time use (don't cache)
### Symptom: All tokens revoked unexpectedly
**Cause:** User re-authorized your app or removed it
**Solution:**
- Detect 401/4741 errors
- Prompt user to re-authorize
---
## Next Steps
- **Implement auto-refresh** → [../examples/token-refresh.md](../examples/token-refresh.md)
- **Fix token errors** → [../troubleshooting/token-issues.md](../troubleshooting/token-issues.md)
- **Understand OAuth flows** → [oauth-flows.md](oauth-flows.md)