API reference
POST /v1/challenges
Request a single-use challenge before every enroll or match.
POST /v1/challenges
Issues a single-use challenge bound to your app. It expires after 60 seconds. Every enroll and match needs a fresh one. See Challenges and replay protection.
Credential: publishable key, from an allowed Origin. No request body.
Request
curl -X POST https://api.facecard.dev/v1/challenges \
-H "X-FaceCard-Key: fc_pk_live_xxx" \
-H "Origin: https://app.example.com"Response
200 OK
{
"challenge_id": "ch_...",
"nonce": "Zm9vYmFy...",
"expires_at": "2026-10-14T12:01:00.000Z"
}| Field | Type | Description |
|---|---|---|
challenge_id | string | Pass this as challenge_id to enroll or match. |
nonce | string | 32 random bytes, base64url. |
expires_at | string | ISO 8601 time. 60 seconds after issue. |
Errors
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | Missing or invalid key. |
| 403 | origin_not_allowed | The Origin is not on the app's allow list. |
| 429 | rate_limited | More than 30 requests a minute from this IP. |
| 429 | plan_limit_reached | The team is over its monthly auth limit. |