Alaqan Pass API

Seamless biometric verification using palm recognition technology

Overview

Alaqan Pass provides a seamless biometric verification solution using palm recognition technology. Integrate with just two API calls and a single redirect URL to enable secure user enrollment and identification.

How It Works

1

Create Session

Call our API to generate a verification URL

2

Redirect User

Send user to the URL in their browser

3

Palm Scan

User completes verification on our page

4

Receive Result

Get notified via webhook

1. Create Session — Call our API to generate a unique verification URL
2. Redirect User — Send the user to the URL in their browser
3. User Completes — User follows the palm scanning flow on our hosted page
4. Receive Result — Get notified via webhook when verification completes

Authentication

All API requests require authentication using an API key sent in the X-API-Key header.

bash Copy

curl -X POST "https://api.pass.alaqan.com/v1/enroll" \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Endpoints

POSTEnroll User

Creates a verification session for enrolling a new user's palm biometrics.

endpoint Copy

POST /enroll

Headers

Query Parameters

Request Body

json Copy

{
  "external_id": "EMP-12345",
  "username": "John Doe",
  "metadata": {
    "department": "Engineering",
    "access_level": "standard"
  }
}

Response

json Copy

{
  "url": "https://pass.alaqan.com/enroll/abc123xyz..."
}

Example

bash Copy

curl -X POST "https://api.pass.alaqan.com/v1/enroll?language=en" \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "EMP-12345",
    "username": "John Doe",
    "metadata": {"department": "Engineering"}
  }'

Error Responses

POSTIdentify User

Creates a verification session for identifying an existing user by their palm.

endpoint Copy

POST /identify

Headers

Query Parameters

Response

json Copy

{
  "url": "https://pass.alaqan.com/identify/xyz789abc..."
}

Example

bash Copy

curl -X POST "https://api.pass.alaqan.com/v1/identify?language=en" \
  -H "X-API-Key: xxxxxxxxxxxxxxxxxxxx"

Error Responses

Webhooks

Receive real-time notifications when a verification session completes. Configure your webhook URL in the partner dashboard.

Webhook Payload

When a session completes, we send a POST request to your configured webhook URL.

json Copy

{
  "event": "completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "enroll",
    "external_id": "EMP-12345",
    "username": "John Doe",
    "metadata": {
      "department": "Engineering"
    },
    "language": "en"
  }
}

Event Types

Payload Fields

Webhook Security

All webhook requests include an HMAC signature in the X-Webhook-Signature header.

http Copy

X-Webhook-Signature: sha256=<signature>

Verifying the Signature

JavaScript:

javascript Copy

const crypto = require('crypto');

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

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

Python:

python Copy

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

If your endpoint returns a non-200 status code, we retry with exponential backoff:

After 5 failed attempts, the webhook is marked as failed and will be disabled in the dashboard.

Session Flow

URL Expiration

• Session URLs expire after 15 minutes by default
• Expired sessions return 400 Bad Request with message link expired
• Used sessions return 410 Gone if accessed again

Rate Limits

Rate limit headers are included in all responses:

http Copy

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

Error Handling

All errors follow a consistent format:

json Copy

{
  "message": "external_id is required"
}

HTTP Status Codes

Support

Technical Support

support@alaqan.com

Business Inquiries

sales@alaqan.com