API Keys
API keys authenticate requests to recognition endpoints (enroll, verify, identify, liveness). Each key is scoped to a single collection, carries its own rate limit, and can optionally restrict access to a list of IP addresses or CIDR ranges.
Keys are stored as SHA-256 hashes. The plaintext key is only returned once at creation. If lost, the key must be regenerated.
Creating an API key
API keys are created from the dashboard under API Keys → New Key. Key management endpoints are CORS-restricted to the dashboard and are not accessible from external applications.
When creating a key you select the target collection, set an optional rate limit override, and optionally restrict access to specific IP addresses. The full key value is shown once only. Copy it immediately and store it securely in your environment or secrets manager.
Key format
All API keys follow the format fr_live_<32 hex chars> for production and fr_test_<32 hex chars> for test environments.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Human-readable label for this key. |
| collection_id | string | Yes | The collection this key grants access to. |
| rate_limit | integer | No | Requests per minute (RPM). Defaults to plan limit. |
| allowed_ips | string[] | No | IP addresses or CIDR ranges. Empty = allow all. |
Managing keys in the dashboard
- List: The API Keys page shows all keys with their name, collection, last-used timestamp, and a masked key prefix for identification.
- Update: Edit a key to change its name, rate limit, or IP whitelist.
- Revoke / delete: Immediately invalidates the key. Any in-flight requests using the key will fail with
INVALID_API_KEY. - Regenerate: Issues a new key value while keeping the same settings. The old value is invalidated.
Key limits by plan
| Plan | Keys per member | Max RPM per key |
|---|---|---|
| Free | 1 | 20 |
| Startup | 5 | 100 |
| Enterprise | 20 | 500 |
IP whitelisting examples
// Allow a single IP
"allowed_ips": ["198.51.100.42"]
// Allow a subnet (CIDR notation)
"allowed_ips": ["10.0.0.0/8"]
// Multiple entries
"allowed_ips": ["203.0.113.0/24", "198.51.100.0/24", "192.0.2.5"]
// Allow all IPs (default)
"allowed_ips": []