API REFERENCE

`POST /v1/enroll`

Capture a user's biometric reference. Computes a 512-dimensional embedding from the supplied frames, encrypts it under the per-tenant key, and stores it indexed by user_id. Photos are not retained — only the encrypted embedding.

Request

POST /v1/enroll
Authorization: Bearer lorica-prod-...
Content-Type: application/json
X-Lorica-Idempotency-Key: enr_xK2mP9nL3jH

{
  "user_id": "usr_4Z9X2fK8mPq",
  "frames": [
    "data:image/jpeg;base64,/9j/4AAQ...",
    "data:image/jpeg;base64,/9j/4AAQ..."
  ]
}

Body parameters

Field	Type	Required	Description
`user_id`	string	yes	Your stable identifier for this user. Opaque to Lorica.
`frames`	array of strings	yes	1–5 JPEG-encoded base64 image strings. More frames produce a stronger embedding; 2–3 is typical.

Response — 200 OK

{
  "user_id": "usr_4Z9X2fK8mPq",
  "enrolled_at": 1720123456,
  "frames_used": 2,
  "embedding_id": "emb_pX7nL3kT9bV"
}

Response — error codes

HTTP	Code	Meaning
400	`invalid_request`	Required field missing or malformed
409	`already_enrolled`	`user_id` already has an embedding (use `/v1/delete` first to re-enroll)
422	`no_face_detected`	None of the supplied frames contains a detectable face
422	`multiple_faces_detected`	One or more frames contains more than one face
422	`quality_below_threshold`	Frames pass face detection but resolution/blur/lighting fall below enrollment quality bar

Tip

Capture the user's enrollment frames in a controlled flow — neutral lighting, no glasses, face fills 30–60% of the frame. The quality of the enrollment embedding bounds the quality of every subsequent verify match for this user.