Skip to main content
The BioKey Server exposes three REST API endpoints for biometric authentication. All endpoints accept and return JSON.

​
POST /enroll

Enroll a new user identity with their public key and device information.

​
Request

​
userId
string
required
Unique identifier for the user
​
publicKey
string
required
64-character hex-encoded public key generated from biometric data
​
deviceId
string
required
Unique identifier for the user’s device
​
method
string
default:"rawid"
Biometric method used (e.g., ‘rawid’, ‘faceid’, ‘touchid’)

​
Response

​
ok
boolean
Whether enrollment was successful
​
userId
string
The enrolled user ID
​
publicKey
string
The enrolled public key
​
method
string
The biometric method used

​
Status Codes

  • 200: Successfully enrolled
  • 400: Missing required fields or invalid publicKey format (must be 64 characters)
  • 500: Enrollment failed (database error)

​
Example

curl -X POST https://your-server.com/enroll \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "publicKey": "a1b2c3d4e5f6...",
    "deviceId": "device456",
    "method": "rawid"
  }'
Response
{
  "ok": true,
  "userId": "user123",
  "publicKey": "a1b2c3d4e5f6...",
  "method": "rawid"
}

​
GET /challenge

Generate a new authentication challenge. Challenges are valid for 5 minutes.

​
Response

​
challenge
string
A 64-character hex-encoded random challenge

​
Status Codes

  • 200: Challenge generated successfully

​
Example

curl https://your-server.com/challenge
Response
{
  "challenge": "7f8e9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e"
}

​
POST /verify

Verify a user’s identity using a challenge. Challenges are single-use and expire after 5 minutes.

​
Request

​
userId
string
required
The user ID to verify
​
challenge
string
required
The challenge obtained from GET /challenge

​
Response

​
verified
boolean
Whether verification was successful
​
publicKey
string
The user’s public key (returned on success)
​
userId
string
The verified user ID
​
method
string
The biometric method associated with this identity

​
Status Codes

  • 200: Successfully verified
  • 400: Missing required fields
  • 401: Invalid or expired challenge
  • 404: Unknown userId

​
Example

curl -X POST https://your-server.com/verify \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "challenge": "7f8e9d0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e"
  }'
Response
{
  "verified": true,
  "publicKey": "a1b2c3d4e5f6...",
  "userId": "user123",
  "method": "rawid"
}

​
Error Responses

All endpoints return error responses in the following format: 
{
  "error": "Error message",
  "detail": "Additional error details (optional)"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us