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	/auth/face/register	JWT	Register face biometric
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

---

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 + Face Biometric verification:

• POST /auth/devices/register — required if user has already registered a face
• POST /v2/keyshare/recover — always required

FaceTec Fields:

Field	Type	Description
face_scan	string	Base64-encoded face scan from FaceTec SDK
audit_trail_image	string	Base64-encoded high-quality audit image
low_quality_audit_trail_image	string	Base64-encoded low-quality audit image
user_agent	string	Client's user-agent string (required by FaceTec)

---

Error Codes

All errors follow this format:

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