API Reference

The Xident API allows you to verify tokens, manage users, and integrate advanced features.

Base URL

https://api.xident.io/v1

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer sk_live_your_secret_key

Use your Secret Key (sk_*) for all backend API calls. Never expose this key in client-side code.

Token Verification

Verify a Token

Verify a one-time token returned from the verification flow.

POST /tokens/verify

Request Body

{
  "token": "tok_abc123..."
}

Response

{
  "verified": true,
  "age": 25,
  "country": "US",
  "xident_id": "xid_abc123",
  "liveness_score": 0.95,
  "methods_completed": ["liveness", "age_estimation"],
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "user_id": "your-user-123"
  }
}

Response Fields

Field Type Description
verified boolean Whether verification was successful
age number Estimated age of the user
country string ISO country code
xident_id string User's Xident ID (if they have one)
liveness_score number Confidence score (0-1)
methods_completed array Verification methods used
metadata object Custom data passed in start()

SDK Endpoints

Check Requirements

Get verification requirements for your project.

POST /requirements/check

Request Body

{
  "api_key": "pk_live_xxx"
}

Response

{
  "requirements": {
    "min_age": 18,
    "liveness_required": true,
    "document_required": false
  },
  "project_name": "My Website"
}

Face 2FA

Register Face

Enroll a user's face for 2FA on your site.

POST /face-2fa/register

Request Body

{
  "user_id": "your-user-123",
  "face_image": "base64_encoded_image..."
}

Response

{
  "success": true,
  "face_id": "face_abc123",
  "enrolled_at": "2024-01-15T10:30:00Z"
}

Verify Face

Authenticate a user via face match.

POST /face-2fa/verify

Request Body

{
  "user_id": "your-user-123",
  "face_image": "base64_encoded_image..."
}

Response

{
  "verified": true,
  "confidence": 0.97,
  "face_id": "face_abc123"
}

Blacklist

Check Blacklist

Check if a face matches any in your blacklist.

POST /blacklist/check

Request Body

{
  "face_image": "base64_encoded_image..."
}

Response (No Match)

{
  "match_found": false,
  "matches": []
}

Response (Match Found)

{
  "match_found": true,
  "matches": [
    {
      "blacklist_id": "bl_abc123",
      "similarity": 0.94,
      "reason": "fraud",
      "added_at": "2024-01-10T08:00:00Z"
    }
  ]
}

Add to Blacklist

Add a face to your blacklist.

POST /blacklist/add

Request Body

{
  "face_image": "base64_encoded_image...",
  "reason": "fraud",
  "metadata": {
    "original_user_id": "user-456"
  }
}

Response

{
  "success": true,
  "blacklist_id": "bl_abc123"
}

Usage

Get Usage Statistics

Retrieve usage data for your project.

GET /usage

Query Parameters

Parameter Type Description
start_date string Start date (ISO 8601)
end_date string End date (ISO 8601)

Response

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "summary": {
    "total_verifications": 1523,
    "full_verifications": 892,
    "token_verifications": 631,
    "total_cost": 45.67
  },
  "by_type": [
    {
      "type": "full",
      "count": 892,
      "cost": 35.68
    },
    {
      "type": "token",
      "count": 631,
      "cost": 9.47
    }
  ]
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "invalid_token",
    "message": "The token has expired or already been used",
    "details": {}
  }
}

Error Codes

Code HTTP Status Description
invalid_token 400 Token is invalid, expired, or already used
unauthorized 401 Invalid or missing API key
forbidden 403 API key doesn't have permission
not_found 404 Resource not found
rate_limited 429 Too many requests
internal_error 500 Server error

Rate Limits

Endpoint Limit
/tokens/verify 100 requests/minute
/face-2fa/* 60 requests/minute
/blacklist/* 30 requests/minute
/usage 10 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315200

Webhooks

Configure webhooks in your Dashboard to receive real-time events.

Event Types

Event Description
verification.completed User completed verification
verification.failed Verification failed
token.verified Token was verified

Webhook Payload

{
  "id": "evt_abc123",
  "type": "verification.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "verification_id": "ver_xyz789",
    "user_id": "your-user-123",
    "age": 25,
    "methods_completed": ["liveness", "age_estimation"]
  }
}

Signature Verification

Verify webhook signatures to ensure authenticity:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Next Steps