🔐 Authentication

Learn how to authenticate your API requests using API keys.

Overview

The rPPG API uses API key authentication via Bearer tokens. All API requests must include your API key in the Authorization header.

Getting Your API Key

1. Contact your administrator to request an API key
2. Your key will be in the format: rppg_live_xxxxxxxxxxxxxxxx
3. Store it securely (never commit to version control)

Using Your API Key

With the SDK (Recommended)

import { RPPGClient } from 'rppg-api-client';

const client = new RPPGClient({
  apiKey: 'rppg_live_your_key_here',
  baseUrl: 'https://api.yourdomain.com/api'
});

// SDK automatically adds the Authorization header to all requests

With Direct HTTP Requests

curl -X POST https://api.yourdomain.com/api/v1/scan-session \
  -H "Authorization: Bearer rppg_live_your_key_here" \
  -H "Content-Type: application/json"

JavaScript Fetch

const response = await fetch('https://api.yourdomain.com/api/v1/scan-session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rppg_live_your_key_here',
    'Content-Type': 'application/json'
  }
});

API Key Security Best Practices

✅ DO:

• Store API keys in environment variables
• Use different keys for development and production
• Rotate keys periodically
• Restrict key usage to specific IP addresses (if available)
• Monitor key usage for suspicious activity

❌ DON'T:

• Commit API keys to version control
• Share keys in public forums or documentation
• Use production keys in client-side code
• Hard-code keys in your application

Storing API Keys Securely

Node.js / Server-Side

Use environment variables:

# .env file (add to .gitignore!)
RPPG_API_KEY=rppg_live_your_key_here
RPPG_API_URL=https://api.yourdomain.com/api

// Load from environment
require('dotenv').config();

const client = new RPPGClient({
  apiKey: process.env.RPPG_API_KEY,
  baseUrl: process.env.RPPG_API_URL
});

Frontend Applications

Never expose API keys in client-side code. Instead:

1. Create a backend proxy:

// Your backend server
app.post('/api/analyze-video', async (req, res) => {
  const client = new RPPGClient({
    apiKey: process.env.RPPG_API_KEY, // Server-side only
    baseUrl: process.env.RPPG_API_URL
  });
  
  const vitals = await client.analyzeVideo(req.file);
  res.json(vitals);
});

2. Call your backend from the frontend:

// Frontend code - no API key exposed
const formData = new FormData();
formData.append('video', videoFile);

const response = await fetch('/api/analyze-video', {
  method: 'POST',
  body: formData
});

Development Mode

For local testing, the API supports a development mode with relaxed authentication:

// Set DEV_MODE=true on the backend
const client = new RPPGClient({
  apiKey: 'dev-key', // Any value works in dev mode
  baseUrl: 'http://localhost/api'
});

⚠️ Warning: Development mode should never be enabled in production.

Authentication Errors

401 Unauthorized

{
  "detail": "Invalid or missing API key"
}

Causes:

• Missing Authorization header
• Invalid API key format
• Expired or revoked key

Solution: Check your API key and ensure it's properly formatted.

403 Forbidden

{
  "detail": "API key does not have permission for this resource"
}

Causes:

• Key doesn't have required permissions
• IP address not whitelisted

Solution: Contact your administrator to verify key permissions.

Key Formats

Live Keys (Production)

rppg_live_xxxxxxxxxxxxxxxx

Test Keys (Sandbox)

rppg_test_xxxxxxxxxxxxxxxx

See Testing & Sandbox for test environment details.

Rate Limiting

API keys are subject to rate limits:

• Default: 60 requests per minute
• Per session: Check X-RateLimit-* response headers

See Rate Limits for details on quotas and throttling.

Rotating Your API Key

To rotate your API key:

1. Request a new key from your administrator
2. Update your environment variables
3. Deploy the change to your application
4. Verify the new key works
5. Request deactivation of the old key

Troubleshooting

"API key not working after deployment"

Check that:

• Environment variables are set in production
• Key is not accidentally trimmed (no spaces)
• Using correct key for environment (test vs. live)

"Getting 401 errors intermittently"

• Verify you're not hitting rate limits
• Check for multiple API keys in different environments
• Ensure key hasn't been revoked

Next Steps

• SDK Libraries → - Initialize the SDK with your key
• Testing & Sandbox → - Get test credentials
• Rate Limits → - Understand usage quotas