Documentation

Veridexa Developer API

Base URL: https://veridexa.io. All authenticated endpoints require a bearer token — get one from the dashboard.

Authentication

Send your API key as a bearer token on every authenticated request:

Authorization: Bearer vxd_live_abc123…

Keys come in two environments: vxd_test_… for sandbox work and vxd_live_… for production. Both share the same free-plan quota.

Quotas & rate limits

Free plan: 100 requests / month, 10 requests / minute. Quotas are enforced atomically server-side. When a limit is hit you get HTTP 429 with aRetry-After header (minute limit) orreason: "monthly_limit_exceeded" in the body.

Endpoints

GET/api/v1/biometrics/healthPublic

Service discovery. Returns version, schema, endpoint list, and plan limits. No auth.

Response
{
  "ok": true,
  "service": "veridexa-developer-api",
  "version": "v1",
  "endpoints": [...],
  "plans": { "developer_free": { "monthlyLimit": 100, "minuteLimit": 10 } }
}
POST/api/v1/biometrics/enrollBearer auth

Enroll a biometric sample (face image) and return an opaque template plus quality metrics.

Request
{
  "schemaVersion": "biometric-core.api/v1",
  "modality": "face",
  "sample": { "imageBase64": "<base64 JPEG/PNG>" }
}
Response
{
  "ok": true,
  "result": {
    "template": { "modality": "face", "version": 1, "vector": "<base64>" },
    "quality": { "score": 0.87, "checks": {...} }
  }
}
POST/api/v1/biometrics/compareBearer auth

1:1 comparison of two templates. Returns similarity score and pass/fail against the modality threshold.

Request
{
  "schemaVersion": "biometric-core.api/v1",
  "modality": "face",
  "reference": { "modality": "face", "version": 1, "vector": "<base64>" },
  "probe":     { "modality": "face", "version": 1, "vector": "<base64>" }
}
Response
{
  "ok": true,
  "result": { "score": 0.83, "passed": true, "threshold": 0.62 }
}
POST/api/v1/biometrics/livenessBearer auth

Not enabled. This endpoint returns 503 liveness_not_available until a certified provider is registered.

Request
{
  "schemaVersion": "biometric-core.api/v1",
  "modality": "face",
  "frames": [ { "imageBase64": "..." }, { "imageBase64": "..." } ]
}
Response
{ "ok": false, "error": { "code": "liveness_not_available" } }
POST/api/v1/biometrics/emrtdBearer auth

eMRTD (ePassport) chip ingest. Runs Passive Authentication over the SOD, parses DG1 MRZ, returns per-DG metadata.

Request
{
  "sessionId": "<uuid>",
  "protocol": "BAC",
  "dg1": "<base64>",
  "dg2": "<base64>",
  "sod": "<base64>"
}
Response
{
  "ok": true,
  "result": {
    "sessionId": "...",
    "protocol": "BAC",
    "passiveAuthentication": { "sodParsed": true, "dgHashesVerified": true, ... },
    "mrz": { "documentNumber": "...", "surname": "...", ... },
    "dgMetadata": { "dg1": { "tag": "61", "hashHex": "..." } }
  }
}
GET/api/v1/biometrics/devicesBearer auth

List registered biometric device adapters (mock adapters for face, fingerprint, signature).

Response
{ "ok": true, "result": { "devices": [...] } }

Error codes

CodeMeaning
401 unauthorized:no_bearerMissing Authorization header.
401 unauthorized:malformedKey is not vxd_test_… or vxd_live_… of the expected length.
401 unauthorized:not_foundKey prefix does not match any active key.
401 unauthorized:revokedKey has been revoked.
401 unauthorized:expiredKey expiry timestamp is in the past.
401 unauthorized:hash_mismatchFull key hash does not match the stored hash.
429 quota_exceeded:minute_limit_exceededPer-minute burst exceeded. Retry after Retry-After seconds.
429 quota_exceeded:monthly_limit_exceededFree-plan monthly cap reached. Resets on the 1st of next month (UTC).
400 invalid_jsonRequest body is not valid JSON.
400 invalid_payloadZod validation failed. See details.flatten() output.
500 internal_errorUnexpected server error. Correlate with x-request-id.

CORS

CORS is enabled with Access-Control-Allow-Origin: * and permitsAuthorization, Content-Type,X-Request-ID. Every response carries anx-request-id — include it in bug reports.

Client library

A TypeScript reference wrapper is available in-repo atsrc/lib/veridexa-biometric-sdk/. It's a thin fetch-based wrapper — copy it into your project or call the REST endpoints directly with any HTTP client.

Related resources

Developer platform

Get a key, open your dashboard, and view usage.

Developer Showcase

Copy-ready snippets in 9 languages for every endpoint.

Playground

Try live endpoints from the browser with your key.

Biometrics platform

The modalities and engines behind these endpoints.

Fraud Detection

Document forensics — same auth model, same audit trail.

Documentation home

Quickstarts, SDKs, webhooks, and security guides.