Developer Integration

Integrate HumanPass without leaving the product design system behind.

Use the hosted browser verification flow, wire session results into your backend, and keep experimental widget or mobile paths clearly labeled until they are proven.

Run Demo Read Docs

import HumanPassClient from '@humanpass/sdk-web';

const client = new HumanPassClient({
  apiKey: 'sk_live_xxxx',
  apiUrl: 'https://api.humanpass.io',
  verifyUrl: 'https://humanpass.io/verify'
});

const result = await client.verify({
  uniquenessPolicy: 'warn',
  metadata: { checkoutId: 'order_42' }
});

console.log(result.sessionId, result.token);

Current Truth

Recommended integration path

The hosted /verify flow and @humanpass/sdk-web are the strongest current developer-facing path. Use /api/v1/sessions for session creation, signals, and finalize. Legacy /api/v1/widget/*routes and mobile wrappers are useful scaffolding but should not be described as equally production-ready.

Create a session

Use the v1 API to create a browser verification session for your user.

Open hosted verify

Send users through the hosted HumanPass verification surface instead of embedding unproven camera code.

Receive results

Finalize the session and consume webhooks or pass-token checks from your backend.

Gate with policy

Apply your own app rules to approved, rejected, duplicate, or expired verification results.

Workspace Ready

API key surface

This UI shows the intended credential management shape. Use server-side storage for real keys and rotate them from the authenticated dashboard.

Production key

hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Integration Modes

Choose the smallest honest path

The product supports multiple integration concepts, but the visual and copy now distinguish proven surfaces from experimental scaffolding.

Hosted verify

Recommended

The clearest current integration path. Your app opens HumanPass /verify and receives the result.

Web SDK

Current

@humanpass/sdk-web wraps the hosted verify flow for browser and React surfaces.

REST API

Current

Use sessions, signals, finalize, and pass verification endpoints from your backend.

Widget/mobile

Experimental

Legacy widget and mobile wrappers are useful scaffolding, not the primary demo proof path.

REST API

Backend surfaces for sessions and decisions

Use these endpoints to create sessions, receive browser signals, finalize verification, and check pass tokens.

POST/api/v1/auth/login

Authenticate and receive access tokens.

POST/api/v1/sessions

Create a hosted verification session.

GET/api/v1/sessions/:id/salt

Fetch a masked uniqueness salt for the session.

POST/api/v1/sessions/:id/signals

Submit browser verification signals.

POST/api/v1/sessions/:id/finalize

Finalize a session and return the decision.

POST/api/v1/passes/verify

Demo-oriented pass-token verification endpoint.

GET/health

API health check.

Webhook and callbacks

Use callback URLs to receive verification events after finalize. Keep route-family wording specific in demos: /api/v1/sessions is the recommended API family, while widget-prefixed routes are legacy/secondary.

verification.completed

POST your configured callback URL when the session reaches a final state.

verification.failed

POST your configured callback URL when the session reaches a final state.

verification.duplicate

POST your configured callback URL when the session reaches a final state.

Payload Example

{
  "event": "verification.completed",
  "sessionId": "sess_abc123xyz789",
  "decision": "approved",
  "passToken": "hp_x9y8z7w6v5u4",
  "expiresAt": "2026-04-21T13:00:00.000Z",
  "riskLevel": "low",
  "riskScore": 0.08,
  "riskFlags": [],
  "timestamp": "2026-04-21T12:00:00.000Z",
  "metadata": {
    "profile": "specter",
    "challengesCompleted": 4,
    "processingTimeMs": 3400
  }
}

Model Profiles

Expose profile maturity without overselling it

Integrators can see which verification modes are stable, alternate, or experimental while Specter remains the safest baseline.

Specter

Proven baseline

Default demo-safe profile and safest production-facing claim.

Phantom

Alternate

YuNet + v2 anti-spoof fallback with lighter directional prompts.

Argus

Experimental

Accuracy-oriented fallback profile; no live SCRFD claim.

Fortress

Experimental

Stricter policy profile using available assets only; no fake SCRFD/V1 claim.

Next Step

Test the hosted flow before wiring policy.

Run a live verification session, inspect the decision payload, then connect the result to your app-side authorization policy. The authenticated developer dashboard provides the fuller integration workspace.

Run Demo Open Dashboard