Integration Guide

Xident is a backend-first integration. Your server creates a verification session with its secret key, redirects the user to the Xident widget, and reads the result back. This guide covers the full flow and the options at each step. For a minimal walkthrough, start with the Quick Start.

The flow

  1. Create a session — your backend calls POST /verify/v1/init (secret key) → verify_url.
  2. Redirect the user's browser to verify_url.
  3. Callback — Xident redirects the user back to your callback_url with ?status&token&user_id.
  4. Read the result — your backend calls GET /verify/v1/result/{token} (secret key).

Security: Keep your secret key (sk_live_…) server-side only. Never trust the callback URL's status for authorization — always read the result server-side with GET /verify/v1/result/{token}.

Prerequisites

  • A secret key (sk_live_…) from your dashboard
  • A callback URL on your domain (HTTPS in production; http://localhost allowed in development)
  • A backend route to create the session and another to handle the callback

Step 1: Create a verification session

Call POST /verify/v1/init from your backend:

curl https://api.xident.io/verify/v1/init \
  -X POST \
  -H "X-API-Key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
        "callback_url": "https://yoursite.com/verified",
        "min_age": 18,
        "purpose": "age_verification",
        "user_id": "your-user-123",
        "theme": "system",
        "locale": "en"
      }'

The response gives you a one-time init token and the URL to send the user to:

{
  "success": true,
  "data": {
    "token": "xit_9f8e7d6c5b4a...",
    "verify_url": "https://verify.xident.io?t=xit_9f8e7d6c5b4a..."
  }
}

Init options

FieldRequiredDescription
callback_urlYesWhere Xident redirects the user afterward. HTTPS, or http://localhost in dev.
min_ageYes*Age threshold to check: 1–99 (0–99 when purpose is id_verification). *Required for age verification.
purposeNoage_verification (default) or id_verification
success_url / failed_urlNoOptional explicit redirect targets instead of a single callback_url
user_idNoYour user identifier — echoed back on the callback as user_id
themeNolight, dark, or system
localeNoen, es, fr, de, pt, ar, zh, ja, hi, nl
metadataNoOpaque string echoed back to you unchanged

Step 2: Redirect the user

Redirect the user's browser to the verify_url from Step 1 (for example, an HTTP 302 from your backend route). The widget runs on verify.xident.io and handles liveness, age estimation, and document capture as required. The one-time init token (xit_…) is carried in the URL as ?t= and expires in 10 minutes.

Step 3: Handle the callback

When verification finishes, Xident redirects the user to your callback_url:

https://yoursite.com/verified?status=success&token=xtk_abc123&user_id=your-user-123
ParameterDescription
statussuccess, failed, or cancelled
tokenResult token (xtk_…) — pass to the result endpoint
user_idYour user_id if you supplied one at init

Step 4: Read the result (server-side)

Fetch the authoritative result with your secret key:

curl https://api.xident.io/verify/v1/result/xtk_abc123 \
  -H "X-API-Key: sk_live_your_secret_key"

data.status is the authoritative outcome (completed = passed, failed, canceled). See the API Reference for the full response schema.

Language SDKs

Server SDKs wrap these two calls (plus optional webhook verification). Use the one for your stack:

Security Best Practices

  1. Use HTTPS — callback URLs must be HTTPS (except http://localhost in development).
  2. Read results server-side — never trust the callback status alone; always call GET /verify/v1/result/{token} with your secret key.
  3. Keep the secret key server-side — never ship sk_live_… to a browser or mobile app. A publishable pk_live_… exists for optional client-side widget embedding only.
  4. Use X-API-Key — Xident authenticates with the X-API-Key header, not Authorization: Bearer.
  5. Token expiration — the init token (xit_…) expires in 10 minutes and is single-use.

Testing

  • Use your test secret key (sk_test_…) for sandbox mode.
  • http://localhost:* callback URLs are allowed (no HTTPS required).

Advanced: client-side embedding

If you prefer to trigger verification from the browser instead of redirecting from your backend, a publishable key (pk_live_…) can call POST /verify/v1/init client-side. This is optional and not required for the standard backend flow; results must still be read server-side with your secret key.

Next Steps