FR-APIaaS - Face Recognition API as a Service

FR-APIaaS uses two separate authentication modes with clearly different purposes. Understanding which one applies to your situation is the first step.

The key distinction

Your application only ever needs an API key. JWT is for the dashboard and one-time setup. Log in, create collections and API keys, then your app uses those keys exclusively. Never embed your dashboard credentials in application code.

	Bearer JWT	API Key (X-API-Key)
Who uses it	You (the developer / admin)	Your application / backend
How obtained	Log in to the dashboard	Created in the dashboard, copied to your app
Create collections	✅	❌
Manage API keys	✅	❌
Manage members & billing	✅	❌
Enroll / delete faces	✅ (dashboard)	✅ (your app)
Verify / identify / liveness	✅ (playground)	✅ (your app)
Expiry	1 hour (refresh token available)	Never (until revoked)

JWT Authentication (Dashboard & Setup)

JWT is used exclusively by the dashboard for administrative tasks: creating collections, managing API keys, managing members, billing, and viewing audit logs.

Management endpoints are restricted to the dashboard origin and are not accessible from external applications. To perform setup tasks, log in to the dashboard and use the UI. No API calls required from your side.

API Key Authentication (Your Application)

API keys are what you embed in your backend application or server. They authenticate face management and recognition requests scoped to a specific collection:

Enroll, list, get, update, and delete faces
1:1 verification and 1:N identification
Liveness detection
Batch operations and export

Pass the key in the X-API-Key header:

X-API-Key: fr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to a specific collection and carry their own rate limits. See API Keys for how to create and manage them.

IP Whitelisting

Each API key can optionally restrict access to a list of allowed IP addresses or CIDR ranges. Requests from non-whitelisted IPs receive a 403 Forbidden response with error code IP_NOT_ALLOWED. Leave the list empty to allow all IPs.

{
  "name": "production-server",
  "collection_id": "col_01j8...",
  "allowed_ips": ["203.0.113.0/24", "198.51.100.42"]
}

Rate Limiting

Rate limits are enforced per API key using a sliding window counter. Limits are expressed in requests per minute (RPM). When exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 12 seconds."
  }
}

Auth Endpoints

Method	Path	Description
POST	/api/v1/auth/register	Create a new account
POST	/api/v1/auth/login	Obtain access + refresh tokens
POST	/api/v1/auth/refresh	Refresh access token
POST	/api/v1/auth/logout	Invalidate session
POST	/api/v1/auth/forgot-password	Send password reset email
POST	/api/v1/auth/reset-password	Reset password with token
GET	/api/v1/auth/verify-email	Verify email address

Two-Factor Authentication

FR-APIaaS supports TOTP-based 2FA (Google Authenticator, Authy, etc.). When enabled, the login flow returns a requires_2fa: true flag. Submit the 6-digit code to /api/v1/auth/2fa/verify to complete the login and receive tokens.