SDK

Use the Human Gateway SDK.

The Human Gateway SDK lets partners launch hosted Verify/Auth flows, receive frontend UX results, and verify signed backend callbacks with server helpers.

Install

Add the SDK to your frontend application. Server-side callback helpers are also exported from the same package.

Install SDK

npm install @human-gateway/sdk

Configure the client

Initialize the SDK with your Human Gateway project ID. For production integrations, keep project and action values in environment variables instead of hardcoding real values directly in source files or public examples.

Frontend environment variables

NEXT_PUBLIC_HG_PROJECT_ID=project_xxx
NEXT_PUBLIC_HG_VERIFY_ACTION_KEY=hg_verify_action_key_xxx
NEXT_PUBLIC_HG_AUTH_ACTION_KEY=hg_auth_action_key_xxx

Create SDK client

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

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

Frontend project and action values are not callback secrets, but keeping them configurable reduces accidental exposure and makes sandbox and production environments easier to manage.

Project and action model

A project represents one partner integration. An action represents a specific Verify or Auth flow inside that project.

Use Verify actions for one-time or repeated human verification flows.
Use Auth actions when you need a partner-scoped verified-human session.
Pass explicit actionKey values in production to avoid ambiguity.

Run Verify

Use Verify when you need to confirm that a user is a real human for a specific product action without creating a Human Gateway auth session.

Verify with SDK

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);
  },
});

if (result.verified_human) {
  // Update UI immediately.
  // Persist durable state after a valid signed callback.
}

Verify result

{
  "success": true,
  "verified_human": true,
  "verification_level": "orb",
  "unique_for_partner": true,
  "already_verified": false,
  "project_id": "project_xxx"
}

Run Auth

Use Auth when you need a private verified-human login/session flow. Auth creates a partner-scoped user reference and Human Gateway auth session reference.

Auth with SDK

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

if (result.success && result.verified_human) {
  // Update UI immediately.
  // Reconcile durable access from your backend callback flow.
}

Auth result

{
  "success": true,
  "event": "auth.completed",
  "verified_human": true,
  "verification_level": "orb",
  "partner_user_id": "puser_xxx",
  "auth_session_id": "authsess_xxx",
  "project_id": "project_xxx",
  "expires_at": "2026-08-01T00:00:00.000Z"
}

SDK options

The SDK is designed to support hosted flows first. During early access, popup mode is the primary supported browser flow. Partner-facing integrations should use sandbox before production.

SDK options

type HumanGatewayOptions = {
  projectId: string;
  environment?: "production" | "sandbox";
  mode?: "auto" | "popup" | "modal" | "redirect";
  baseUrl?: string;
  timeoutMs?: number;
};

Both production and sandbox use the hosted Human Gateway domain by default. For local testing, previews, or controlled internal validation, pass an explicit baseUrl.

Call hg.verify() or hg.auth() directly from a user action such as a button click. Modern browsers may block popups opened after delayed promises, timers, or background tasks.

Frontend result vs backend callback

SDK results are useful for immediate UI updates. Signed backend callbacks should be treated as the durable source of truth for persistent state, access control, and database updates.

A malicious client can manipulate frontend state. A valid Human Gateway callback cannot be forged without the project callback secret.

Continue with the callbacks guide to verify signed backend events.

Server helpers

Server helpers are exported from @human-gateway/sdk/server. Use them only in backend code because they require your project callback secret.

Server callback helper

import {
  HumanGatewayCallbackError,
  verifyCallback,
} from "@human-gateway/sdk/server";

const callback = verifyCallback({
  body,
  headers: request.headers,
  secret: process.env.HG_CALLBACK_SECRET!,
  expectedProjectId: process.env.HG_PROJECT_ID,
});

Never expose HG_CALLBACK_SECRET in frontend code, browser logs, public repositories, screenshots, or variables using a NEXT_PUBLIC_ prefix.

Error handling

Handle common SDK errors so users can retry safely when a popup is blocked, closed, timed out, or the hosted flow fails.

Error handling

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

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

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

  if (result.verified_human) {
    // Update UI.
  }
} catch (error) {
  if (error instanceof HumanGatewayError) {
    if (error.code === "user_closed") {
      // The user closed the popup.
    }

    if (error.code === "popup_blocked") {
      // Ask the user to allow popups and retry from a direct click.
    }

    if (error.code === "timeout") {
      // The flow took too long.
    }

    if (error.code === "verification_failed") {
      // The hosted verification flow did not complete successfully.
    }
  }
}

SDK error codes

popup_blocked
user_closed
timeout
invalid_message
invalid_origin
verification_failed
auth_failed
unknown_error

Privacy model

Human Gateway does not expose raw World ID nullifiers, raw World ID proofs, biometric data, identity documents, government identity data, or unnecessary personal identity information through standard SDK responses or callbacks.

Partners may receive scoped operational fields such as verified_human, verification_level, unique_for_partner, already_verified, partner_user_id, auth_session_id, project_id, and timestamps, depending on the flow.

verification_level can be device, document, secure_document, orb, or null. Human Gateway only returns the value provided by World ID. It does not infer, upgrade, or claim a stronger verification level.

Integration checklist

SDK checklist

SDK integration checklist
- Install @human-gateway/sdk
- Store project/action values in environment variables
- Use explicit actionKey values in production
- Launch Verify/Auth from direct user actions
- Treat frontend results as UX signals
- Configure a full backend callback URL
- Verify signed callbacks on the backend
- Keep HG_CALLBACK_SECRET out of frontend code
- Process callback event_id idempotently
- Review Privacy, Terms, Security, and Cookies policies

Next steps

Start with the Quickstart for the recommended integration path, then use the Callbacks guide to verify backend events safely.