Entrust | API Documentation

1. Start a Session

Initialize a secure verification session. This returns a set of random liveness challenges and a cryptographic token.

POST /api/session/start

Header	Type	Description
`x-api-key`	String	Your unique client API key for authentication.

2. Complete Verification

Submit the computed 128-D facial descriptor and liveness score. The API will perform deduplication and save the verified identity to the database.

POST /api/session/complete

Body Parameter	Type	Description
`sessionId`	String	The ID returned from start endpoint.
`token`	String	The secure token from start endpoint.
`analysis.descriptor`	Array	128D Float32Array from face-api.
`analysis.referencePhoto`	String	Base64 encoded JPEG.

Start Session Examples

cURL Node.js Python

curl -X POST https://api.secretcircle.com/v1/session/start \
  -H "x-api-key: sk_live_123456789"
  
# Expected Response:
# {
#   "sessionId": "req_8f92bd",
#   "token": "tok_991823",
#   "challenges": ["lookLeft", "lookRight", "blink"]
# }

const fetch = require('node-fetch');

const startSession = async () => {
  const response = await fetch('https://api.secretcircle.com/v1/session/start', {
    method: 'POST',
    headers: { 'x-api-key': 'sk_live_123456789' }
  });
  const data = await response.json();
  console.log("Session ID:", data.sessionId);
  return data;
};

import requests

url = "https://api.secretcircle.com/v1/session/start"
headers = { "x-api-key": "sk_live_123456789" }

response = requests.post(url, headers=headers)
data = response.json()
print("Session ID:", data.get("sessionId"))

Complete Verification Examples

cURL Node.js Python

curl -X POST https://api.secretcircle.com/v1/session/complete \
  -H "x-api-key: sk_live_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "req_8f92bd",
    "token": "tok_991823",
    "analysis": {
      "descriptor": [0.12, -0.04, 0.99],
      "referencePhoto": "data:image/jpeg;base64,/9j/4AAQSkZJ..."
    }
  }'

const fetch = require('node-fetch');

// Complete Verification
const verifyIdentity = async (payload) => {
  const response = await fetch('https://api.secretcircle.com/v1/session/complete', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'sk_live_123456789'
    },
    body: JSON.stringify(payload)
  });
  
  const result = await response.json();
  
  if (result.isDuplicate) {
    console.error("Duplicate Face Detected: User already exists.");
    return false;
  }
  
  return result.verified;
};

import requests

url = "https://api.secretcircle.com/v1/session/complete"
headers = {
    "x-api-key": "sk_live_123456789",
    "Content-Type": "application/json"
}

data = {
    "sessionId": "req_8f92bd",
    "token": "tok_991823",
    "analysis": {
        "descriptor": [0.12, -0.04, 0.99],
        "referencePhoto": "data:image/jpeg;base64,/9j/4AAQSkZJ..."
    }
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result.get("isDuplicate"):
    print("Duplicate Face Detected!")
else:
    print(f"Verified: {result.get('verified')}")

Expected Response

{
  "verified": true,          // Boolean: True if liveness & face matching passed
  "isDuplicate": false,      // Boolean: True if the face already exists (if duplicates restricted)
  "error": "..."            // String: Present only if verification fails
}

Face Liveness Verification API

1. Start a Session

2. Complete Verification

Start Session Examples

Complete Verification Examples

Expected Response

Developer Portal