API Reference

Base URL & Headers

https://<your-auth-service-domain>

All requests and responses use JSON:

Content-Type: application/json

Endpoint Summary

Method	Endpoint	Auth	Description
POST	/auth/users/register	JWT	Register new user
GET	/auth/devices/challenge/:device_verifying_key	JWT	Get challenge for device registration
POST	/auth/devices/register	JWT + Device Signature + Face (conditional)	Register device verifying key
POST	/v2/auth/devices/register-and-recover	JWT + Device Signature + Face	Register device and recover keyshares in one call
POST	/v2/auth/face/init-session	JWT	Relay the FaceTec SDK initialization request
POST	/v2/auth/face/process	JWT + write:face or read:face	Create or continue a face enrollment or match scan
GET	/v2/keys	JWT	List user's MPC keys
GET	/v2/devices	JWT	List user's devices
POST	/v2/keyshare/backup	JWT	Save encrypted keyshares
POST	/v2/keyshare/recover	JWT + Face	Fetch encrypted keyshares
GET	/transactions	JWT	Get transaction history
GET	/v2/face	JWT	Get face registration status
GET	/v2/admin/groups	JWT + update:default_policy	List policy groups (admin)
GET	/v2/admin/groups/:group_id	JWT + update:default_policy	Get a group's policy (admin)
PUT	/v2/admin/groups/:group_id/policy	JWT + update:default_policy	Replace a group's policy (admin)

---

Authentication Methods

JWT Authentication

All endpoints require a valid Access Token (JWT) from the External Auth Service (e.g., Auth0).

Authorization: Bearer <access_token>

JWT Claims Used:

Claim	Description
sub	User identifier (auth0_id)
aud	Must include API identifier
exp	Token expiration time
scope	Granted permissions

Device Signature Authentication

Device registration endpoints require an additional Device Signature to prove possession of the device's private key (stored in Secure Enclave).

Signature Generation:

1. Create JSON_MESSAGE containing request body fields
2. Canonicalize JSON_MESSAGE (sort keys alphabetically, remove whitespace) per RFC 8785
3. Compute: M = SHA256(bytes(canonicalize(JSON_MESSAGE)))
4. Generate: DER-encoded ECDSA signature of M (NIST P-256 curve)
5. Hex-encode the signature

Step-Up Authentication (JWT + Face)

Sensitive operations require JWT + a successful face match session:

• POST /auth/devices/register: required if the user has already enrolled a face
• POST /v2/auth/devices/register-and-recover: always required
• POST /v2/keyshare/recover: always required

The first request of a match scan to POST /v2/auth/face/process returns a face_session_id. The app includes that ID in every later request for the scan. Once the scan completes with succeeded: true, the app sends the same ID in the sensitive operation's request body:

Field	Type	Description
face_session_id	string	ID of a match scan that completed with succeeded: true

Auth-svc spends the session when it accepts the sensitive operation. Each successful match authorizes exactly one operation. The validity window begins when the match completes and lasts FACETEC_SESSION_EXPIRY_SECONDS, which is 300 seconds by default.

---

Error Codes

All errors follow this format:

{
  "error": "Human-readable error description",
  "code": 100101
}