OAuth2 Flow & Token Management

Automate OAuth2 token management with KnoxCall. Never manually refresh tokens again - KnoxCall handles OAuth2 authentication, token refresh, and rotation automatically.

The OAuth2 Token Problem

Without KnoxCall, managing OAuth2 tokens is painful:

// Your code becomes a mess of token management
let accessToken = 'ya29.a0AfH6SMB...';
let refreshToken = '1//0gUc-sQZ...';
let expiresAt = Date.now() + 3600000;

async function makeAPICall() {
  // Check if token expired
  if (Date.now() >= expiresAt) {
    // Refresh the token
    const response = await fetch('https://oauth2.googleapis.com/token', {
      method: 'POST',
      body: JSON.stringify({
        client_id: 'YOUR_CLIENT_ID',
        client_secret: 'YOUR_CLIENT_SECRET',
        refresh_token: refreshToken,
        grant_type: 'refresh_token',
      }),
    });

    const data = await response.json();
    accessToken = data.access_token;
    refreshToken = data.refresh_token || refreshToken;
    expiresAt = Date.now() + (data.expires_in * 1000);

    // Save to database
    await saveTokensToDatabase({accessToken, refreshToken, expiresAt});
  }

  // Finally make the actual API call
  return await fetch('https://www.googleapis.com/drive/v3/files', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  });
}

Problems:

100+ lines of token management code
Must securely store tokens
Handle refresh failures
Deal with token rotation
Race conditions in concurrent requests

With KnoxCall

// Your code is clean and simple
const response = await fetch('https://a1b2c3d4.acme.knoxcall.com/drive/v3/files', {
  headers: {
    'x-knoxcall-route': 'google-drive',
    'x-knoxcall-key': process.env.KNOXCALL_API_KEY,
  },
});

KnoxCall automatically:

✅ Refreshes tokens before expiry
✅ Handles token rotation
✅ Stores tokens encrypted (AES-256)
✅ Manages concurrent requests
✅ Retries on auth failures
✅ Zero downtime, zero code

OAuth Clients page

The OAuth Clients page (Settings → Security → OAuth Clients) is the unified surface for managing OAuth 2.1 in KnoxCall. It has three tabs:

Tab	What it shows
Clients	Your registered OAuth2 client applications — client ID, allowed scopes, grant types
Workload Identity	Workload Identity Federation bindings — DPoP binding status, last-used timestamp
Active Tokens	Currently live access tokens across all clients — expiry, last-used, DPoP binding status

There are two distinct OAuth flows in KnoxCall:

OAuth2 Secrets (Secrets page) — store provider tokens (Google, Stripe, etc.) that KnoxCall auto-refreshes and injects into route headers. Use these for outbound API calls through your routes.
OAuth Client Registrations (OAuth Clients page) — register OAuth clients that grant access to the KnoxCall API itself. Use these for Workload Identity Federation bindings and programmatic API access with DPoP-bound tokens.

Use the Active Tokens tab as your primary monitoring surface for live token state — you can see which tokens are DPoP-bound, when they expire, and when they were last used, without needing to set up an alert rule.

Supported OAuth2 Providers

KnoxCall supports all OAuth2-compliant providers:

Pre-Configured Providers

Google

Google Drive
Gmail API
Google Calendar
Google Sheets

Microsoft

Office 365
OneDrive
Outlook API
Microsoft Graph

Salesforce

Salesforce API
Force.com

Slack

Slack API
Slack Webhooks

Custom OAuth2 Providers

Any OAuth2-compliant API:

Stripe
GitHub
Shopify
QuickBooks
Custom APIs

Setting Up OAuth2

Step 1: Register Your Application

First, register your application with the OAuth2 provider:

Google
Microsoft
Custom

Go to Google Cloud Console
Create a new project or select existing
Enable the API you want to use (Drive, Gmail, etc.)
Go to Credentials → Create Credentials → OAuth 2.0 Client ID
Application type: Web application
Authorized redirect URIs: https://oauth.knoxcall.com/callback
Save Client ID and Client Secret

Go to Azure Portal
Navigate to Azure Active Directory → App registrations
Click New registration
Name: Your app name
Redirect URI: https://oauth.knoxcall.com/callback
Create and save Application (client) ID
Go to Certificates & secrets → Create client secret
Save the secret value

For custom OAuth2 providers, you need:

Authorization URL (e.g., https://example.com/oauth/authorize)
Token URL (e.g., https://example.com/oauth/token)
Client ID
Client Secret
Scopes (permissions needed)

Step 2: Create OAuth2 Secret in KnoxCall

Navigate to Secrets → Add Secret
Configure:

Name:

google-drive-oauth

Type:

OAuth2

Provider: Select from dropdown or choose “Custom” Client ID:

123456789-abc.apps.googleusercontent.com

Client Secret:

GOCSPX-abc123def456

Scopes:

https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.file

Redirect URI:

https://oauth.knoxcall.com/callback

Click Save

Step 3: Complete OAuth2 Authorization

After creating the secret, you need to authorize it:

Click Authorize button next to your OAuth2 secret
You’ll be redirected to the provider’s login page
Log in and grant permissions
You’ll be redirected back to KnoxCall
Tokens are automatically saved and encrypted

✅ Done! KnoxCall now has your OAuth2 tokens.

Step 4: Use in Routes

Create or edit a route
Target Base URL: https://www.googleapis.com (for Google APIs)
In Header Injection, add:

{
  "Authorization": "Bearer {{secret:google-drive-oauth}}"
}

Save route

Now all requests to this route will include the OAuth2 token automatically!

How Token Refresh Works

KnoxCall uses intelligent token refresh that adapts to each provider’s token lifetime:

Dynamic Refresh Threshold

Tokens are automatically refreshed when 25% of their lifetime remains (or 5 minutes before expiry, whichever is greater):

Short-lived token (20 min):
    ↓
Refreshes at 15 min (25% = 5 min remaining) ✅
    ↓
Long-lived token (24 hours):
    ↓
Refreshes at 18 hours (25% = 6 hours remaining) ✅
    ↓
Token without expiry info:
    ↓
Refreshes 5 minutes before expiry (fallback) ✅

Example: 1-hour token lifecycle

Token issued: 1:00 PM (expires at 2:00 PM)
    ↓
Request at 1:40 PM ✅ Uses current token (40 min remaining = 67%)
    ↓
Request at 1:46 PM 🔄 Refreshes token (14 min remaining = 23%)
    ↓
New token issued: 1:46 PM (expires at 2:46 PM)
    ↓
Old token still valid until 2:00 PM (overlap period)
    ↓
Request succeeds with new token ✅

Why 75% threshold?

Short tokens (< 20 min): Prevents last-second refresh failures
Long tokens (> 1 hour): Avoids unnecessary early refreshes
Variable tokens: Adapts to each provider’s expiry time
Network delays: Buffer time for slow refresh responses

Benefits:

Adapts to any token lifetime (5 min to 90 days)
Zero downtime during refresh
No race conditions
Automatic retry on failure
Graceful fallback if expires_in missing
Token rotation handled transparently

Token Storage & Security

OAuth2 tokens are stored with military-grade security:

Encryption

Algorithm: AES-256-GCM
Key derivation: PBKDF2 with 100,000 iterations
Master key: Stored in AWS KMS (or your key management)

Access Control

Tokens are:

❌ Never exposed in logs
❌ Never returned via API
❌ Never visible in dashboard
✅ Only decrypted at request time
✅ Tenant-isolated
✅ RBAC-protected

Token Versioning

Every token refresh creates a new version:

Version 1: Initial authorization
Version 2: First refresh (24 hours later)
Version 3: Second refresh (48 hours later)
...

You can:

View token refresh history
Roll back to previous version (if needed)
See when tokens were last refreshed

Handling Token Revocation

If a user revokes access or tokens expire:

Automatic Detection

KnoxCall detects revoked tokens:

Request to API → 401 Unauthorized
    ↓
KnoxCall attempts refresh → 400 Invalid Grant
    ↓
Token marked as REVOKED
    ↓
Alert sent to admins
    ↓
Requests return: "OAuth token revoked, please reauthorize"

Reauthorization

To reauthorize:

Go to Secrets → Select OAuth2 secret
Status shows: REVOKED
Click Reauthorize
Complete OAuth2 flow again
New tokens saved

Multi-User OAuth2

For multi-user applications, each user needs their own tokens:

Approach 1: Per-User Secrets

Create a separate secret for each user:

Secret: user-123-google-oauth
Secret: user-456-google-oauth
Secret: user-789-google-oauth

Use client IDs to route to the right secret:

curl https://a1b2c3d4.acme.knoxcall.com/drive/files \
  -H "x-knoxcall-route: google-drive" \
  -H "x-knoxcall-client-id: user-123" \
  -H "x-knoxcall-key: tk_abc..."

Approach 2: Dynamic Secret Selection

Use KnoxCall’s dynamic secret selection:

{
  "Authorization": "Bearer {{secret:oauth-{user_id}}}"
}

KnoxCall will replace {user_id} with the value from request context.

OAuth2 with Refresh Token Rotation

Some providers (like Google) rotate refresh tokens:

Initial Authorization:
  access_token: ya29.a0...
  refresh_token: 1//0gU...
  expires_in: 3600

First Refresh:
  access_token: ya29.a0... (new)
  refresh_token: 1//0hV... (new, old one invalidated!)
  expires_in: 3600

KnoxCall handles this automatically:

Saves new refresh token
Invalidates old refresh token
No manual intervention needed

Scopes & Permissions

Different scopes for different use cases:

Google Drive (Read-Only)

https://www.googleapis.com/auth/drive.readonly

Google Drive (Full Access)

https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.file

Gmail (Send Email)

https://www.googleapis.com/auth/gmail.send

Microsoft Graph (Calendar)

Calendars.Read
Calendars.ReadWrite

Request minimum scopes needed. Users are more likely to grant limited permissions.

Testing OAuth2 Routes

After setting up OAuth2:

curl https://a1b2c3d4.acme.knoxcall.com/drive/v3/files \
  -H "x-knoxcall-route: google-drive" \
  -H "x-knoxcall-key: tk_abc123..."

You should receive a successful response with your Google Drive files.

Monitoring OAuth2 Tokens

Token Health Dashboard

Monitor your OAuth2 tokens:

Last refreshed: When was the token last refreshed
Expires at: When will the token expire
Refresh attempts: How many times has refresh been attempted
Status: Active, Expiring Soon, Revoked, Failed

Alerts

Set up alerts for OAuth2 issues:

Navigate to Alerts → Add Alert
Type: OAuth2 Token Issues
Configure:

Alert when:
- Token refresh fails 3 times
- Token expires in < 24 hours without refresh
- Token is revoked by user

Notification channels:
- Email to: admin@company.com
- Slack channel: #oauth-alerts

Best Practices

1. Use Separate Secrets Per Environment

Production:
  Secret: google-oauth-prod

Staging:
  Secret: google-oauth-staging

Development:
  Secret: google-oauth-dev

2. Request Minimal Scopes

Only request permissions you actually need: ❌ Bad:

https://www.googleapis.com/auth/drive (full access)

✅ Good:

https://www.googleapis.com/auth/drive.readonly

3. Monitor Token Health

Set up monitoring:

Alert on refresh failures
Alert on token expiration
Monitor refresh success rate

4. Handle Revocation Gracefully

When tokens are revoked:

Show clear error message to users
Provide reauthorization link
Don’t expose technical details

5. Test Token Refresh

Manually trigger refresh to test:

Go to secret details
Click Force Refresh
Check logs for success

Troubleshooting

”Invalid refresh token” errors

Causes:

User revoked access
Refresh token expired (rare)
OAuth app was deleted

Fix:

Reauthorize the secret
Check OAuth app is still active
Verify redirect URI matches

Token refresh fails silently

Check:

Alert configuration
Error logs in KnoxCall
OAuth provider’s API status

Concurrent request issues

Solution: KnoxCall handles this automatically with request queuing. If you see issues, contact support.

Wrong scope errors

HTTP/1.1 403 Forbidden
{
  "error": "insufficient_scope"
}

Fix:

Edit OAuth2 secret
Add required scopes
Reauthorize

Next Steps

Secret Management

Learn about managing secrets

Request Signing

Add signature verification

Advanced Configuration

Advanced route configuration

Monitoring

Monitor API usage and errors

📊 Statistics

Level: intermediate
Time: 20 minutes

🏷️ Tags

oauth2, authentication, tokens, google, microsoft

​OAuth2 Flow & Token Management

​The OAuth2 Token Problem

​With KnoxCall

​OAuth Clients page

​Supported OAuth2 Providers

​Pre-Configured Providers

Google

Microsoft

Salesforce

Slack

​Custom OAuth2 Providers

​Setting Up OAuth2

​Step 1: Register Your Application

​Step 2: Create OAuth2 Secret in KnoxCall

​Step 3: Complete OAuth2 Authorization

​Step 4: Use in Routes

​How Token Refresh Works

​Dynamic Refresh Threshold

​Token Storage & Security

​Encryption

​Access Control

​Token Versioning

​Handling Token Revocation

​Automatic Detection

​Reauthorization

​Multi-User OAuth2

​Approach 1: Per-User Secrets

​Approach 2: Dynamic Secret Selection

​OAuth2 with Refresh Token Rotation

​Scopes & Permissions

​Google Drive (Read-Only)

​Google Drive (Full Access)

​Gmail (Send Email)

​Microsoft Graph (Calendar)

​Testing OAuth2 Routes

​Monitoring OAuth2 Tokens

​Token Health Dashboard

​Alerts

​Best Practices

​1. Use Separate Secrets Per Environment

​2. Request Minimal Scopes

​3. Monitor Token Health

​4. Handle Revocation Gracefully

​5. Test Token Refresh

​Troubleshooting

​”Invalid refresh token” errors

​Token refresh fails silently

​Concurrent request issues

​Wrong scope errors

​Next Steps

Secret Management

Request Signing

Advanced Configuration

Monitoring

📊 Statistics

🏷️ Tags

OAuth2 Flow & Token Management

The OAuth2 Token Problem

With KnoxCall

OAuth Clients page

Supported OAuth2 Providers

Pre-Configured Providers

Custom OAuth2 Providers

Setting Up OAuth2

Step 1: Register Your Application

Step 2: Create OAuth2 Secret in KnoxCall

Step 3: Complete OAuth2 Authorization

Step 4: Use in Routes

How Token Refresh Works

Dynamic Refresh Threshold

Token Storage & Security

Encryption

Access Control

Token Versioning

Handling Token Revocation

Automatic Detection

Reauthorization

Multi-User OAuth2

Approach 1: Per-User Secrets

Approach 2: Dynamic Secret Selection

OAuth2 with Refresh Token Rotation

Scopes & Permissions

Google Drive (Read-Only)

Google Drive (Full Access)

Gmail (Send Email)

Microsoft Graph (Calendar)

Testing OAuth2 Routes

Monitoring OAuth2 Tokens

Token Health Dashboard

Alerts

Best Practices

1. Use Separate Secrets Per Environment

2. Request Minimal Scopes

3. Monitor Token Health

4. Handle Revocation Gracefully

5. Test Token Refresh

Troubleshooting

”Invalid refresh token” errors

Token refresh fails silently

Concurrent request issues

Wrong scope errors

Next Steps