Getting Started with Xident

This guide will walk you through integrating Xident age verification into your website in under 5 minutes.

Prerequisites

Before you begin, you'll need:

  • A Xident account (sign up here)
  • A project with API keys
  • A callback URL on your domain (HTTPS required in production)

Step 1: Create a Project

  1. Log in to dashboard.xident.io
  2. Click "Create Project"
  3. Enter your website domain (e.g., example.com)
  4. You'll receive two API keys:
    • Public key (pk_live_...) — for your frontend JS SDK, safe to expose in browser code
    • Secret key (sk_live_...) — for your backend server, never expose in client-side code

Public Key vs Secret Key

The public key (pk_live_) is used by the JS SDK in the browser to call widget-facing endpoints (requirements, liveness, OCR). The secret key (sk_live_) is used by your server-side code (Node.js, Python, PHP, Go) to initialize sessions and retrieve verification results. Both keys use the X-API-Key header.

Step 2: Add the SDK to Your Website

Add the Xident SDK script tag to your HTML, typically in the <head> or before </body>:

<script
  src="https://sdk.xident.io/xident.min.js"
  data-api-key="pk_live_your_public_key"
  data-callback-url="https://yoursite.com/verified"
></script>

Replace:

  • pk_live_your_public_key with your actual public API key
  • https://yoursite.com/verified with your callback URL

Step 3: Add a Verification Button

Add a button that triggers the verification flow:

<button onclick="Xident.start()">
  Verify Your Age
</button>

When clicked, users will be redirected to verify.xident.io to complete verification.

Step 4: Handle the Callback

After verification, users are redirected to your callback URL with query parameters:

https://yoursite.com/verified?token=abc123&status=success

Callback Parameters

Parameter Description
token One-time verification token
status success or cancelled
user_id Your userId if provided in start()

Step 5: Verify the Token (Backend)

Important: Always verify tokens server-side using your secret key (sk_live_...). Never trust client-side results.

Node.js Example

app.get('/verified', async (req, res) => {
  const { token, status } = req.query;

  if (status !== 'success') {
    return res.redirect('/verification-cancelled');
  }

  try {
    const response = await fetch(
      `https://api.xident.io/verify/v1/status/${token}`,
      {
        headers: {
          'X-API-Key': process.env.XIDENT_SECRET_KEY, // sk_live_...
        },
      }
    );

    const { success, data } = await response.json();

    if (success && data.verified && data.above_threshold) {
      req.session.ageVerified = true;
      return res.redirect('/content');
    }
  } catch (error) {
    console.error('Verification error:', error);
  }

  return res.redirect('/verification-failed');
});

Python Example

@app.route('/verified')
def handle_verification():
    token = request.args.get('token')
    status = request.args.get('status')

    if status != 'success':
        return redirect('/verification-cancelled')

    response = requests.get(
        f'https://api.xident.io/verify/v1/status/{token}',
        headers={
            'X-API-Key': os.environ['XIDENT_SECRET_KEY'],  # sk_live_...
        },
    )

    body = response.json()

    if body.get('success') and body['data'].get('above_threshold'):
        session['age_verified'] = True
        return redirect('/content')

    return redirect('/verification-failed')

Verification Response

The status endpoint returns the Xident API envelope format:

{
  "success": true,
  "data": {
    "verified": true,
    "age_threshold": 18,
    "above_threshold": true,
    "country": "US",
    "xident_id": "xid_abc123",
    "methods_completed": ["liveness", "age_estimation"],
    "metadata": {
      "your_custom_field": "value"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-30T10:30:05Z"
  }
}

Key fields: data.verified indicates success, data.above_threshold tells you whether the user is above the required age threshold, and data.age_threshold shows which threshold was checked (e.g. 18, 21).

Testing

For development, you can use:

  • pk_test_xxx / sk_test_xxx API keys (sandbox mode)
  • http://localhost:* callback URLs (no HTTPS required)
<script
  src="https://sdk.xident.io/xident.min.js"
  data-api-key="pk_test_your_test_key"
  data-callback-url="http://localhost:3000/verified"
></script>

Next Steps