What is OAuth and Why Use It?

If you're used to API keys, OAuth might seem complicated. This guide explains what OAuth is, why it's more secure than API keys, and why DoorFlow requires it for building access control integrations.

The Problem with API Keys

Many APIs use a simple API key for authentication:

// API key approach
fetch('https://api.example.com/people', {
  headers: {
    'X-API-Key': 'sk_live_abc123xyz789'
  }
});

How OAuth Fixes These Problems

OAuth 2.0 is an authorization framework that lets users grant limited access to their accounts without sharing passwords or permanent keys.

1. Limited Permissions (Scopes)

OAuth uses "scopes" to request only the permissions you need:

// OAuth approach - request only what you need
scopes: "account.event.access.readonly account.person.readonly"

If your token is compromised, damage is limited to what those scopes allow.

2. User Consent

When a DoorFlow customer connects your app, they see exactly what you're requesting:

"Employee Directory" wants to:
- View people in your account
- View access events

[Authorize] [Deny]

Users understand what access they're granting before approving.

3. Easy Revocation

Customers can revoke access anytime from their DoorFlow account settings. Your token stops working immediately - no need to change code or regenerate keys across all customers.

4. Short-Lived Tokens

OAuth access tokens expire after 1 hour. Even if stolen, they become useless quickly.

{
  "access_token": "eyJhbGci...",
  "expires_in": 3600
}

Your app uses a refresh token to get new access tokens automatically (see Token Refresh guide).

5. Secure by Design

OAuth keeps secrets server-side:

// Frontend: Only client_id (public, safe to expose)
const authUrl = `https://api.doorflow.com/oauth/authorize?client_id=abc123`;

// Backend: client_secret (private, never exposed)
const response = await fetch('https://api.doorflow.com/oauth/token', {
  body: new URLSearchParams({
    client_secret: process.env.CLIENT_SECRET // Server-side only!
  })
});

Your client_secret never leaves your server. Even if your frontend code is inspected, attackers can't get your credentials.

OAuth vs API Keys Comparison

Real-World Example: Visitor Management

You're building a visitor check-in kiosk that creates temporary access.

With API keys (insecure):

// One key with full access
const API_KEY = 'sk_live_dangerous';

// Can do everything:
await createVisitor(API_KEY);      // OK - needed
await unlockAllDoors(API_KEY);     // Dangerous - not needed
await deleteAllPeople(API_KEY);    // Catastrophic - not needed

If this key leaks (logged, exposed in frontend, etc.), attackers have complete control.

With OAuth (secure):

// Request only visitor management scopes
scopes: "account.person account.reservation"

// Can do:
await createVisitor(accessToken);       // OK
await grantTimeLimitedAccess(accessToken); // OK

// Cannot do:
await unlockAllDoors(accessToken);      // 403 Forbidden
await deleteAllPeople(accessToken);     // 403 Forbidden

Even if the token leaks:

• Expires in 1 hour
• Can only create visitors and reservations
• Customer can revoke immediately
• No access to sensitive operations

Is OAuth More Complex?

Yes, initially. But the security benefits are worth it:

Common Questions

scopes: "account.person.readonly account.event.access.readonly"