Understanding Tokens

Tokens are the currency of OAuth. Understanding how they work is crucial for building secure applications.

Token Types

The Token Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│                      TOKEN LIFECYCLE                             │
└─────────────────────────────────────────────────────────────────┘

 User Login           API Calls              Token Refresh
     │                    │                       │
     ▼                    ▼                       ▼
┌─────────┐        ┌─────────────┐         ┌─────────────┐
│  OAuth  │        │   Access    │         │  Refresh    │
│  Flow   │───────>│   Token     │───exp──>│   Token     │
└─────────┘        │  (1 hour)   │         │  (30 days)  │
                   └─────────────┘         └─────────────┘
                         │                       │
                         ▼                       ▼
                   ┌─────────────┐         ┌─────────────┐
                   │   API       │         │   New       │
                   │   Request   │         │   Access    │
                   └─────────────┘         │   Token     │
                                           └─────────────┘

Access Token Usage

// Making API requests with access token
const response = await fetch('https://api.github.com/user', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/json'
  }
});

// The server validates the token and returns data
const user = await response.json();

Token Refresh Flow

// When access token expires, use refresh token to get a new one
async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://oauth2.googleapis.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken,
      grant_type: 'refresh_token'
    })
  });

  const tokens = await response.json();
  return {
    accessToken: tokens.access_token,
    // Some providers rotate refresh tokens
    refreshToken: tokens.refresh_token || refreshToken
  };
}

// Example: Auto-refresh before expiration
class TokenManager {
  constructor(tokens) {
    this.accessToken = tokens.access_token;
    this.refreshToken = tokens.refresh_token;
    this.expiresAt = Date.now() + (tokens.expires_in * 1000);
  }

  async getValidToken() {
    // Refresh 5 minutes before expiration
    if (Date.now() > this.expiresAt - 300000) {
      const newTokens = await refreshAccessToken(this.refreshToken);
      this.accessToken = newTokens.accessToken;
      this.refreshToken = newTokens.refreshToken;
      this.expiresAt = Date.now() + 3600000; // 1 hour
    }
    return this.accessToken;
  }
}

JWT: JSON Web Tokens

Most modern OAuth implementations use JWTs (pronounced "jots") for access tokens.

JWT Structure

A JWT has three parts separated by dots:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.POstGetfAytaZS82wHcjoTyoqhMyxXiWdR7Nn7A29DNSl0EiXLdwJ6xC6AfgZWF1bOsS_TuYI3OG85AmiExREkrS6tDfTQ2B3WXlrr-wp5AokiRbz3_oB4OxG-W9KcEEbDRcZc0nH3L7LzYptiy1PtAylQGxHTWZXtGz4ht0bAecBgmpdgXMguEIcoqPJ1n3pIWk_dUZegpqx0Lka21H6XxUTxiy8OcaarA8zdnPUnV6AmNP3ecFawIFYdvJB_cm-GvpCSbr8G8y_Mllj8f4x9nBH8pQux89_6gUY618iYv7tuPWBFfEbLxtF2pZS6YC1aSfLQxeNe8djT9YjpvRZA

{
  "alg": "RS256",
  "typ": "JWT"
}

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622
}

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  privateKey
)

Common JWT Claims

Decoding JWTs

// JWTs can be decoded (but not verified) client-side
function decodeJWT(token) {
  const [header, payload, signature] = token.split('.');
  return {
    header: JSON.parse(atob(header)),
    payload: JSON.parse(atob(payload)),
    signature: signature
  };
}

// Example
const decoded = decodeJWT(accessToken);
console.log(decoded.payload);
// { sub: "user123", name: "John", exp: 1699999999, scope: "read write" }

// Check if expired
const isExpired = decoded.payload.exp * 1000 < Date.now();

ID Tokens vs Access Tokens

Opaque vs Self-Contained Tokens

Real-World: Stripe's Token Strategy

Stripe uses different token patterns for different purposes:

// API Key (long-lived, opaque) - for server-to-server
const stripe = require('stripe')('sk_live_...');

// Publishable Key (restricted) - for client-side
// pk_live_... can only create tokens, not read data

// OAuth Access Token - for connected accounts
const response = await stripe.oauth.token({
  grant_type: 'authorization_code',
  code: 'ac_...'
});
// Returns access_token (for API) and refresh_token

Token Storage Best Practices

Key Takeaways

Next up: OpenID Connect - Building identity on top of OAuth 2.0.