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 manage an auth session.

A Verify action belongs to a Human Gateway project. Partners launch Verify from the frontend SDK and should persist durable state only after receiving a valid 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

Store your public project and Verify action values in environment variables. They are not callback secrets, but keeping them configurable reduces accidental exposure and makes sandbox and production setups easier to manage.

NEXT_PUBLIC_HG_PROJECT_ID=project_xxx
NEXT_PUBLIC_HG_VERIFY_ACTION_KEY=hg_verify_action_key_xxx

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,
  "verification_level": "orb",
  "unique_for_partner": true,
  "already_verified": false,
  "project_id": "project_xxx"
}

• verified_human indicates whether the flow completed successfully.
• verification_level indicates the World ID verification level returned for this proof. It can be device, document, secure_document, orb, or null.
• unique_for_partner indicates whether this is a new partner-scoped human for that project/action context.
• already_verified helps your UI handle returning users gracefully.

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

{
  "event_id": "evt_xxx",
  "event": "verification.completed",
  "success": true,
  "verified_human": true,
  "verification_level": "orb",
  "unique_for_partner": 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, verification_level, unique_for_partner, already_verified, project_id, action information, event IDs, and timestamps.

Human Gateway only returns the verification level provided by World ID. It does not infer, upgrade, or claim a stronger verification level.

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.