Product-aligned docs for the hosted HumanPass verification flow.
Start with the hosted browser verification path, then connect sessions, webhooks, and pass-token checks where your app needs them. Experimental widget and mobile surfaces are labeled honestly.
Use the current proof path first.
The hosted /verify flow, @humanpass/sdk-web, and /api/v1/sessions route family are the clearest current integration surfaces. The older /api/v1/widget/*routes are legacy/secondary for the embeddable widget path.
Private by default
Raw face frames stay in the browser. Backend calls receive verification signals, risk outputs, and masked uniqueness state.
Session-first API
Create sessions, submit signals, finalize decisions, and verify pass tokens through the v1 route family.
Mobile is scaffolded
React Native uses hosted verification scaffolding today. Treat native camera and device attestation as roadmap work.
Core endpoints
These are the demo-relevant HTTP surfaces that connect the browser verification flow to HumanPass session and pass-token behavior.
curl -X POST http://localhost:3001/api/v1/sessions \
-H "Content-Type: application/json" \
-d '{
"widgetId": "demo-widget",
"uniquenessPolicy": "warn"
}'/api/v1/sessions. Keep /api/v1/widget/sessions references only when documenting the legacy widget package.Web SDK
HumanPassClient.verify() opens the hosted /verify flow and waits for a result. This is the clearest supported demo path today.
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({
frameShape: 'circle',
language: 'en',
uniquenessPolicy: 'warn',
metadata: { checkoutId: 'order_42' }
});
console.log(result.token, result.sessionId);React entry point
Use the React wrapper from a client component that can open the hosted verify popup. Keep server-side token checks separate from UI verification state.
import { HumanPassButton } from '@humanpass/sdk-web/react';
export function VerifyCTA() {
return (
<HumanPassButton
apiKey="sk_live_xxxx"
options={{ frameShape: 'square', language: 'en' }}
className="rounded-xl bg-[#1c1c1a] px-4 py-3 text-white"
>
Verify You Are Human
</HumanPassButton>
);
}Webhook delivery
HumanPass dispatches verification result events after session finalize. Signatures are represented in the integration surface, but demo teams should confirm the exact route family being used before claiming production-grade webhook hardening.
{
"event": "verification.completed",
"sessionId": "session_123",
"timestamp": "2026-04-14T14:00:00.000Z",
"data": {
"riskLevel": "low",
"isDuplicate": false,
"token": "lp_abcd1234"
}
}