Skip to content

API Key Management

Admin endpoints for creating and managing API keys. Requires HTTP Basic Auth and FACE_API_STORAGE_ENABLED=true.

Keys are stored in plaintext and always visible through the admin API.

POST /api/v1/admin/api-keys

Create a new API key.

Request Body (JSON):

{ "name": "Production App" }

Response (201):

{
  "id": "a1b2c3d4-e5f6-...",
  "key": "xyl_7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
  "name": "Production App",
  "is_active": true,
  "request_count": 0,
  "last_used_at": null,
  "created_at": "2026-04-06T10:30:00+00:00"
}

Example

curl -u admin:password -X POST \
  https://face-api.xylolabs.com/api/v1/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "Production App"}'

GET /api/v1/admin/api-keys

List all keys with usage metrics.

Parameter Type Default Description
page int 1 Page number
per_page int 20 Items per page (1-100) 
curl -u admin:password https://face-api.xylolabs.com/api/v1/admin/api-keys

GET /api/v1/admin/api-keys/{key_id}

Get a specific key with usage stats.

curl -u admin:password https://face-api.xylolabs.com/api/v1/admin/api-keys/a1b2c3d4-...

PATCH /api/v1/admin/api-keys/{key_id}

Update name or revoke/reactivate.

{ "name": "New Name", "is_active": false }

Revoke a key

curl -u admin:password -X PATCH \
  https://face-api.xylolabs.com/api/v1/admin/api-keys/a1b2c3d4-... \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

DELETE /api/v1/admin/api-keys/{key_id}

Permanently delete a key. Returns 204.

curl -u admin:password -X DELETE \
  https://face-api.xylolabs.com/api/v1/admin/api-keys/a1b2c3d4-...

Per-key metrics

Each key tracks:

Field Description
request_count Total API calls made with this key
last_used_at Timestamp of most recent use
is_active Whether the key is accepted or revoked

Metrics update asynchronously after each request.

Using a key

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

curl -X POST https://face-api.xylolabs.com/api/v1/detect \
  -H "X-API-Key: xyl_your_key_here" \
  -F "image=@photo.jpg"

Revoked keys return 403. Missing or invalid keys return 401.