Understanding Security Requirements

DoorFlow has specific security requirements that may differ from consumer APIs you've used. This guide explains what you need to implement and why.

What DoorFlow Requires

1. OAuth Authorization (Always)

Why: Every API request needs user context. DoorFlow needs to know which customer authorized your app and what they allowed you to do.

2. Refresh Tokens (Long-term Access)

Why: Short-lived access tokens limit damage if credentials are compromised. If someone steals an access token, it only works for 1 hour.

See: [OAuth Token Refresh] guide

3. Signed Webhooks (For Event Notifications)

Why: Webhooks control physical access decisions. Someone could fake webhook events to:

• Claim a denied access attempt succeeded
• Trigger false alarms
• Manipulate audit logs

See: [Webhook Security] guide

4. Valid Refresh Token for Webhooks

Why: Webhooks contain sensitive information about building access. If a customer revokes your app, you shouldn't continue receiving their access events.

What this means for you: If webhooks stop arriving, check:

• Has the customer revoked your app access?
• Has your refresh token expired?
• Do you need the customer to re-authorize?

What This Looks Like in Practice

Example: Visitor Management System

You're building an app that:

• Registers visitors at reception
• Creates temporary PINs for visitor access
• Sends access codes via SMS
• Logs visitor check-in/check-out times

Your security implementation:

Security Requirements Checklist

Use this to verify your integration meets DoorFlow's requirements:

OAuth Authorization

• Implement Authorization Code OAuth flow
• Handle user consent/authorization redirect
• Exchange authorization code for tokens
• Store access token and refresh token securely
• Never expose tokens in logs or client-side code

Token Management

• Encrypt refresh tokens in your database
• Detect 401 Unauthorized responses
• Automatically refresh expired access tokens
• Handle refresh token failures gracefully
• Prompt user to re-authorize if refresh fails

Webhook Security (if using webhooks)

• Verify webhook signatures on every request
• Reject webhooks with invalid signatures
• Handle webhook signature verification failures
• Monitor for stopped webhooks (may indicate revoked access)
• Use HTTPS endpoint for receiving webhooks

General Security

• Use HTTPS for all API calls (never HTTP)
• Never log access tokens or refresh tokens
• Implement proper error handling
• Clear tokens when user disconnects your app
• Follow OAuth best practices for your platform

Common Implementation Mistakes

1. Storing Tokens Insecurely

Wrong:

// Stored in plain text
{
  "access_token": "eyJhbGc...",
  "refresh_token": "def5020..."
}

Right:

// Refresh token encrypted
{
  "access_token": "eyJhbGc...",
  "refresh_token": "ENCRYPTED:U2FsdGVk..."
}

2. Not Handling Token Refresh

3. Ignoring Webhook Signatures

Wrong:

Receive webhook → Process immediately

Right:

Receive webhook → Verify signature → Reject if invalid → Process if valid

4. Logging Sensitive Data

Wrong:

console.log('API Response:', response);
// Logs: { access_token: "eyJhbGc...", refresh_token: "def5020..." }

Right:

console.log('API Response:', { status: response.status, id: response.data.id });
// Never log tokens

Why These Requirements Exist

Real-World Scenario: Compromised API Keys

Real-World Scenario: Rogue Employee

Employee at your company goes rogue:

Getting Help

Questions about why these requirements exist?

• [Why Physical Access is Different]
• [Why DoorFlow's Security is Non-Negotiable]

Testing: Use DoorFlow's OAuth demo environment - see [OAuth Application Demo]

Next Steps

Starting fresh?

1. Read [What is OAuth and Why Use It?]
2. Follow [Your First API Request]
3. Implement [OAuth Token Refresh]
4. Review the checklist above
5. Test in demo environment

Have questions?

• Check [Common Workflows] for real examples
• Review [Error Handling] for edge cases
• See [Why DoorFlow's Security is Non-Negotiable] for our philosophy