Docs / Face Recognition And Liveness SDK / Authentication And API Keys

Authentication And API Keys

How your systems call the Face SDK API with API keys, which permissions (scopes) a key can have, and how errors and rate limits are returned.

Send A Key

Every API call needs an API key, in either header, except a few read-only service calls (GET /healthz, GET /v2/info, GET /v2/licence, GET /v2/models, GET /v2/openapi.json) and the first-run setup:

curl http://localhost:8080/v2/identities -H "x-api-key: $API_KEY"

curl http://localhost:8080/v2/identities -H "Authorization: Bearer $API_KEY"

The first key is printed once at the first start. Make more in the dashboard under API keys (admins), each shown once: the server keeps only a hash.

Scopes

Give each system its own key with only the permissions it needs.

Scope	Allows
`enrol`	Add, list and delete people
`verify`	Compare two photos, check a photo against a person, detect faces
`identify`	Search a face among enrolled people
`liveness`	Liveness checks
`streams`	Cameras, the event stream and webcam streams
`admin`	Settings, keys, audit and request logs

A call without the scope answers 403 FORBIDDEN, naming the missing scope.

The dashboard API reference with every call, its parameters and code samples

Requests And Answers

Send photos as multipart form data (-F image=@photo.jpg) or as base64 in JSON. JPEG, PNG, WebP and BMP, up to 10 MB.
Answers are JSON. Every match decision carries the similarity and the threshold that decided it.

Errors

Errors are application/problem+json documents with a stable code:

{
  "type": "https://errors.arsa.technology/face-sdk/pose_yaw",
  "title": "POSE_YAW",
  "status": 422,
  "code": "POSE_YAW",
  "detail": "the face is turned too far"
}

Status	Codes
400	`BAD_REQUEST`, `UNSUPPORTED_IMAGE`, `IMAGE_DIMENSIONS`
401	`UNAUTHORIZED`, `LICENSE_INVALID`
403	`FORBIDDEN`, `FEATURE_DISABLED`
404	`NOT_FOUND`
409	`CONFLICT`, `POSSIBLE_DUPLICATE`, `NEEDS_REENROLMENT`
413	`PAYLOAD_TOO_LARGE`
422	Photo problems: `NO_FACE`, `MULTIPLE_FACES`, `FACE_TOO_SMALL`, `FACE_CROPPED`, `POSE_YAW`, `POSE_PITCH`, `POSE_ROLL`, `BLURRY`, `TOO_DARK`, `TOO_BRIGHT`, `UNEVEN_LIGHT`, `EYES_CLOSED`, `EXPRESSION`, `LOW_QUALITY`, `INCONSISTENT_ENROLMENT_IMAGES`
429	`RATE_LIMITED`, `LICENSE_LIMIT`
503	`QUEUE_FULL` (retry shortly)

The v1 API

Clients written for Face SDK v1 keep working: the v1 API is served at /api/v1 with the same paths, headers and fields. Use a v2 key as x-key-secret. See Changes From v1.

Was this page helpful?

API v2. Updated 2026-11-12