CryptoNets API Documentation

Overview

The CryptoNets API is a biometric enrollment and prediction service that provides secure facial recognition capabilities. The API handles encrypted biometric data for user enrollment, authentication, and management.

Base URL

https://YOUR_DEDICATED_API_URL.privateid.com/node

Note: Each client receives a dedicated API URL. Replace YOUR_DEDICATED_API_URL with your specific endpoint provided by PrivateID.

Authentication

All endpoints require API key authentication via:

Header: x-api-key: <api_key>
Request body: api_key field

Authentication Flow

API keys are validated against the PostgreSQL database
Keys must have status: 'active' to be accepted
Invalid or inactive keys return 403 Forbidden

Rate Limiting

The API uses Express rate limiting middleware (exact configuration depends on deployment settings).

Encryption

The API supports encrypted payloads with versioning:

Header: x-encryption-version (default: 1)
Features are encrypted/decrypted using the provided API key
PUID and GUID values are encrypted in responses

Endpoints

1. API Key Management

Check API Key Validity

POST /node/api-key/checkApiKeyValid

Validates if an API key is active and valid.

cURL Example:

curl --location 'https://YOUR_DEDICATED_API_URL.privateid.com/node/api-key/checkApiKeyValid' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "YOUR_API_KEY"
}'

Request Body:

{
  "api_key": "string"
}

Response:

200 OK: Valid API key

{
  "message": "API Key is valid",
  "status": 0
}

400 Bad Request: Invalid or missing API key

{
  "status": -1,
  "message": "Missing api key"
}

403 Forbidden: Invalid API key

{
  "status": -1,
  "message": "Failed to check api key"
}

2. Enrollment Endpoints

Standard Enrollment

POST /node/{version}/enroll

Enrolls a user with encrypted biometric features.

Path Parameters:

version: Face model version (default: "FACE3_1")

Headers:

x-api-key: API key for authentication
x-encryption-version: Encryption version (default: 1)
x-correlation-id: Optional correlation ID for tracking

cURL Example:

curl --location 'https://YOUR_DEDICATED_API_URL.privateid.com/node/FACE3_1/enroll' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-encryption-version: 1' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "YOUR_API_KEY",
    "features": "ENCRYPTED_FEATURES_STRING"
}'

Request Body:

{
  "api_key": "string",
  "features": "encrypted_string"
}

Decrypted Features Schema:

{
  "features": [
    {
      "type": "string",
      "embedding_vector": [number, ...] // 128-512 numbers
    }
  ]
}

Response:

200 OK: Successful enrollment

{
  "status": 0,
  "message": "ok",
  "enroll_level": 1,
  "puid": "encrypted_puid",
  "guid": "encrypted_guid",
  "score": "number"
}

400 Bad Request: Various validation errors

{
  "status": -2,
  "message": "Enrollment Failed Features not provided."
}

Business Rules:

Features must contain 128-512 dimensional embedding vectors
Duplicate enrollments return existing user data
Bad embeddings are filtered out (threshold: 0.8)
Uses job queue processing with 3 retry attempts

Plain Enrollment

POST /node/plainEnroll

Enrolls a user with unencrypted biometric features.

cURL Example:

curl --location 'https://YOUR_DEDICATED_API_URL.privateid.com/node/plainEnroll' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "YOUR_API_KEY",
    "version": "FACE3_3",
    "features": {
        "type": "face",
        "embedding_vector": [
            0.0333386399,
            0.0532775819,
            -0.0588293932,
            0.0416923612,
            -0.0517333858,
            0.0168136414,
            -0.043994531,
            -0.0783110708,
            0.0394778661,
            0.00980625674
            // ... (truncated for brevity, full vector contains 512 elements)
        ]
    }
}'

Request Body:

{
  "api_key": "string",
  "version": "string", // Optional, defaults to "FACE3_3"
  "features": {
    "type": "string",
    "embedding_vector": [number, ...]
  }
}

Response:

200 OK: New user enrollment

{
  "status": 0,
  "statusCode": 200,
  "message": "Ok",
  "puid": "KW4i4cGr-fv76-YqIE-w7fA-UrAt0FcVyY2q",
  "guid": "T6B5clPB-EJIp-z5EX-wwrb-YGevds03jaeQ",
  "enroll_level": 1
}

200 OK: Already enrolled user

{
  "status": 0,
  "statusCode": 200,
  "message": "User Already Enrolled",
  "puid": "KW4i4cGr-fv76-YqIE-w7fA-UrAt0FcVyY2q",
  "guid": "T6B5clPB-EJIp-z5EX-wwrb-YGevds03jaeQ",
  "enroll_level": 1
}

3. Prediction Endpoints

Standard Prediction

POST /node/{version}/predict

Authenticates a user against enrolled biometric data.

Path Parameters:

version: Face model version (default: "FACE3_1")

Headers:

x-api-key: API key
x-encryption-version: Encryption version

cURL Example:

curl --location 'https://YOUR_DEDICATED_API_URL.privateid.com/node/FACE3_1/predict' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-encryption-version: 1' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "YOUR_API_KEY",
    "features": "ENCRYPTED_FEATURES_STRING",
    "K": 1
}'

Request Body:

{
  "api_key": "string",
  "features": "encrypted_string",
  "K": 1, // Optional: number of matches to return
  "user_identifier": "string" // Optional: specific user lookup
}

Response:

200 OK: User recognized (K=1)

{
  "status": 0,
  "message": "ok",
  "puid": "encrypted_puid",
  "guid": "encrypted_guid",
  "enroll_level": 1,
  "score": "number"
}

200 OK: Multiple matches (K>1)

{
  "status": 0,
  "message": "ok",
  "PI_list": [
    {
      "puid": "encrypted_puid",
      "guid": "encrypted_guid",
      "score": "number"
    }
  ]
}

200 OK: User not recognized

{
  "status": -1,
  "message": "User not enrolled",
  "puid": "-1",
  "guid": "-1",
  "score": "-1"
}

Plain Prediction

POST /node/plainPredict

Prediction with unencrypted features.

cURL Example:

curl --location 'https://YOUR_DEDICATED_API_URL.privateid.com/node/plainPredict' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "YOUR_API_KEY",
    "version": "FACE3_3",
    "features": {
        "type": "face",
        "embedding_vector": [
            0.0333386399,
            0.0532775819,
            -0.0588293932,
            0.0416923612,
            -0.0517333858,
            0.0168136414,
            -0.043994531,
            -0.0783110708,
            0.0394778661,
            0.00980625674
            // ... (truncated for brevity, full vector contains 512 elements)
        ]
    }
}'

Request Body:

{
  "api_key": "string",
  "version": "string", // Optional, defaults to "FACE3_3"
  "features": {
    "type": "string",
    "embedding_vector": [number, ...]
  }
}

Response:

200 OK: Successful prediction

{
  "status": 0,
  "statusCode": 200,
  "message": "ok",
  "puid": "KW4i4cGr-fv76-YqIE-w7fA-UrAt0FcVyY2q",
  "guid": "T6B5clPB-EJIp-z5EX-wwrb-YGevds03jaeQ",
  "score": 0,
  "enroll_level": 1
}

4. User Management

Delete User

POST /node/{version}/deleteUser

Deletes a user and all associated biometric data.

Path Parameters:

version: Face model version (default: "FACE3_1")

Headers:

x-api-key: API key for authentication
x-encryption-version: Encryption version

cURL Example:

curl --location 'https://YOUR_DEDICATED_API_URL.privateid.com/node/FACE3_1/deleteUser' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-encryption-version: 1' \
--header 'Content-Type: application/json' \
--data '{
    "api_key": "YOUR_API_KEY",
    "puid": "ENCRYPTED_PUID"
}'

Request Body:

{
  "api_key": "string",
  "puid": "encrypted_puid"
}

Response:

200 OK: Successful deletion

{
  "status": 200,
  "message": "delete successful"
}

400 Bad Request: User not found

{
  "status": 400,
  "message": "delete failed"
}

500 Internal Server Error: Missing or invalid PUID

{
  "status": -2,
  "message": "Missing PUID."
}

Data Models

API Key Schema

interface ApiKey {
  id: string;           // UUID primary key
  api_key: string;      // Unique API key
  customer_id?: string; // Customer identifier
  api_id?: string;      // API identifier
  usage_plan_id?: string; // Usage plan
  product_code?: string;  // Product code
  status?: string;        // Key status (must be 'active')
  when_created: timestamp; // Creation time
  last_updated: timestamp; // Last update time
}

Feature Schema

interface Feature {
  type: string;                    // Feature type identifier
  embedding_vector: number[];      // 128-512 dimensional vector
}

interface EnrollmentPayload {
  api_key: string;
  features: Feature[];
  metadata?: {
    id: string;
  };
}

interface PredictionPayload {
  api_key: string;
  features: Feature[];
  K?: number;                     // Number of matches (default: 1)
  user_identifier?: string;       // Optional specific user lookup
}

Error Codes

Status	Message	Description
0	OK/Success	Operation completed successfully
-1	Various errors	User not enrolled, validation errors, server errors
-2	Invalid data	Missing features, invalid JSON, authentication errors
152	Face Enrollment Failed	Enrollment specific failure
153	Face Authentication Failed	Authentication specific failure
400	Bad Request	Invalid request format or missing required fields
403	Forbidden	Invalid or inactive API key
500	Internal Server Error	Server-side processing error

Performance & Reliability

Queue Processing

Enrollment operations use BullMQ for reliable processing
3 retry attempts for failed jobs
Performance logging for queue operations

Database Operations

PostgreSQL for structured data (API keys, user mappings)
Vector search capabilities for biometric matching
Redis caching for frequently accessed embeddings
Automatic cleanup of bad embeddings

Security Features

Encrypted payload support with versioned encryption
API key validation with database lookup
ROT13 encoding for plain endpoints
Correlation ID support for request tracking

OpenAPI/Swagger Specification

For developers who prefer working with OpenAPI/Swagger tools, we provide a downloadable specification file:

📄 Download OpenAPI YAML

Using the OpenAPI Specification:

Import into API tools: Use with Postman, Insomnia, or other API testing tools
Generate client SDKs: Auto-generate client libraries for your programming language
Interactive documentation: Host with Swagger UI for interactive testing
Update server URL: Replace YOUR_DEDICATED_API_URL with your actual endpoint

Note: Remember to update the server URL in the specification file with your dedicated API endpoint provided by PrivateID.

Development Notes

Dependencies

Express.js web framework
Multer for file upload handling
Bull/BullMQ for job queuing
TypeORM for database operations
Math.js for vector operations
Custom WASM modules for distance calculations

Environment Configuration

Configurable thresholds per version/factor
Encryption version support
Database connection pooling
Logging with Winston

Testing

Use the package.json scripts:

npm run lint      # Code linting
npm run build     # Production build
npm start         # Start server