Verify real humans without handling identity.

Verify is for product moments where you need to know that a user is a real human for a specific Action, but you do not need Human Gateway to create a PartnerUser identity or manage an auth session.

A Verify Action belongs to one Human Gateway Project. A Project can contain multiple Actions, and Partners should pass the intended actionKey explicitly. Persist durable state only after receiving and verifying the signed backend callback.

Use Verify for anti-sybil checks, voting, claim gating, signup abuse prevention, community access, or other product actions where humanity is useful but a Human Gateway auth session is not required.

Good fit for Verify
- Signup abuse prevention
- One-human voting or polling
- Claim, reward, waitlist, or invite gating
- Community access checks
- Anti-sybil product actions
- Human-only feature unlocks

Not a fit by itself
- KYC
- Civil identity verification
- Sanctions screening
- Age verification
- Legal compliance replacement
- Full account/session management

Project IDs and Verify Action keys are public integration references, not callback secrets. The environment variable names below are local application conventions that keep sandbox, production, and multi-Action configuration explicit.

NEXT_PUBLIC_HG_PROJECT_ID=project_xxx
NEXT_PUBLIC_HG_VERIFY_ACTION_KEY=hg_verify_action_key_xxx

These names are examples only. Human Gateway uses the actual projectId and actionKey values, not your local environment variable names. For multiple Projects or Verify Actions, namespace those values locally as described in the SDK guide.

Launch Verify directly from a user action such as a button click. Browsers may block popups opened after delayed promises, timers, or background tasks.

import { HumanGateway } from "@human-gateway/sdk";

const hg = new HumanGateway({
  projectId: process.env.NEXT_PUBLIC_HG_PROJECT_ID!,
  environment: "production",
});

const result = await hg.verify({
  actionKey: process.env.NEXT_PUBLIC_HG_VERIFY_ACTION_KEY!,
});

if (result.verified_human) {
  // Update UI immediately.
  // Persist durable verified state only after your backend
  // receives and verifies the signed callback.
}

Frontend callbacks help update product UX, analytics, loading states, and retry messaging. They should not replace signed backend callbacks for durable access decisions.

const result = await hg.verify({
  actionKey: process.env.NEXT_PUBLIC_HG_VERIFY_ACTION_KEY!,
  onOpen: () => {
    console.log("Human Gateway Verify opened");
  },
  onSuccess: (result) => {
    console.log("Human Gateway Verify completed", result);
  },
  onError: (error) => {
    console.error("Human Gateway Verify failed", error.code);
  },
});

The SDK returns a frontend result for immediate UX. Treat this as a client-side signal, not your durable backend source of truth.

{
  "success": true,
  "verified_human": true,
  "unique_for_action": true,
  "already_verified": false,
  "project_id": "project_xxx"
}

• verified_human indicates whether the flow completed successfully.
• unique_for_action indicates whether this is the first successful verification for this human within the current Project and Action uniqueness context.
• already_verified indicates that Human Gateway confirmed on the backend that the verified proof maps to existing successful Verify state for the same Project and Action uniqueness context. It is not inferred from a client-side replay signal. This is Verify-state continuity only; it does not create or identify a PartnerUser. A normal repeated World ID 4.0 uniqueness attempt is surfaced by the SDK as an already_verified error rather than as a new successful verification.

A repeated uniqueness attempt does not create a new verification and does not emit a verification.completed callback.

After Verify completes, Human Gateway can send a signed verification.completed callback to your backend. Verify the signature, timestamp, expected Project binding, event, and payload contract before persisting state.

{
  "event_id": "evt_xxx",
  "event": "verification.completed",
  "success": true,
  "verified_human": true,
  "unique_for_action": true,
  "already_verified": false,
  "project_id": "project_xxx",
  "action": "hg_verify_action_key_xxx",
  "created_at": "2026-07-01T00:00:00.000Z"
}

Continue with the callbacks guide for raw body handling, signature verification, timestamp validation, and idempotency.

A good Verify integration should handle success, retries, cancellation, blocked popups, and backend confirmation states clearly.

Recommended UI states
- Not verified
- Verifying
- Verified
- Already verified
- User closed popup
- Popup blocked
- Verification failed
- Waiting for backend confirmation

Human Gateway Verify is designed to avoid exposing raw World ID nullifiers, raw World ID proof data, biometric data, identity documents, government identity data, or unnecessary personal identity information.

Partners receive scoped operational results needed to update product behavior, such as verified_human, unique_for_action, already_verified, project_id, action information, event IDs, and timestamps.

Human Gateway does not expose raw World ID nullifiers or proof material through the standard Verify result. Verify does not expose or create a partner_user_id or auth_session_id; those belong to the separate Auth identity and session model.

Partners remain responsible for their own app security, user notices, consent flows, callback endpoints, secrets, data retention, product eligibility rules, and legal compliance.

Verify is not KYC, civil identity verification, sanctions screening, age verification, or a replacement for regulated compliance checks.

For login/session flows, continue with Auth. For installation and basic setup, review the Quickstart.