Auth

Sign in verified humans privately.

Human Gateway Auth lets partners add a hosted verified-human login flow with partner-scoped users and auth sessions, without handling raw World ID proof internals or unnecessary identity data.

What Auth is

Auth is for product flows where you need a private verified-human login or session reference. It creates a partner-scoped Human Gateway user reference and an auth session reference after a successful hosted proof flow.

Human Gateway Auth does not replace your full application account system unless you choose to build your app around it. Partners remain responsible for their own app session, access rules, logout behavior, data retention, and compliance requirements.

When to use Auth

Use Auth when you need more than a one-time human check. Auth is useful for sign-in, gated areas, dashboards, communities, or product areas where a partner-scoped verified-human session is useful.

Auth use cases

Good fit for Auth
- Sign in with verified-human proof
- Human-only account access
- Private login without collecting identity documents
- Partner-scoped verified-human sessions
- Access gating for dashboards or communities
- Re-authentication for sensitive product actions

Not a fit by itself
- KYC
- Civil identity verification
- Sanctions screening
- Age verification
- AML checks
- Full regulated compliance replacement

Configure frontend values

Store your public project and Auth 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.

Frontend environment variables

NEXT_PUBLIC_HG_PROJECT_ID=project_xxx
NEXT_PUBLIC_HG_AUTH_ACTION_KEY=hg_auth_action_key_xxx

Run Auth with the SDK

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

Auth example

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

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

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

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

Optional frontend callbacks

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

Auth with SDK callbacks

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

Auth result

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

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"
}

partner_user_id is a Human Gateway user reference scoped to your partner/project context.
auth_session_id references the Human Gateway auth session created by the hosted flow.
expires_at indicates when the Human Gateway auth session expires.
verification_level can be device, document, secure_document, orb, or null. Human Gateway only returns the value provided by World ID.

Signed callback

After Auth completes, Human Gateway can send a signed auth.completed callback to your backend. Verify the signature, timestamp, event, and project before granting durable app access or updating your database.

auth.completed

{
  "event_id": "evt_xxx",
  "event": "auth.completed",
  "success": true,
  "verified_human": true,
  "verification_level": "orb",
  "project_id": "project_xxx",
  "partner_id": "partner_xxx",
  "partner_user_id": "puser_xxx",
  "auth_session_id": "authsess_xxx",
  "action": "hg_auth_action_key_xxx",
  "expires_at": "2026-08-01T00:00:00.000Z",
  "created_at": "2026-07-01T00:00:00.000Z"
}

Auth callback handling

if (callback.event === "auth.completed") {
  const payload = callback.payload;

  if (payload.verified_human === true) {
    // Store or reconcile payload.partner_user_id.
    // Store payload.auth_session_id if useful for audit or session mapping.
    // Grant app access according to your own backend session model.
  }
}

Backend environment variables

HG_PROJECT_ID=project_xxx
HG_CALLBACK_SECRET=your_callback_secret

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

Recommended auth flow

Auth flow

1. User clicks "Sign in with Human Gateway".
2. Partner frontend calls hg.auth({ actionKey }).
3. Human Gateway opens a hosted Auth flow.
4. User completes World ID proof.
5. Human Gateway creates a partner-scoped auth session.
6. Partner frontend receives a UX result.
7. Human Gateway sends a signed backend callback.
8. Partner backend verifies the callback.
9. Partner backend links or reconciles the partner_user_id.
10. Partner grants app access according to its own session model.

Session model

Human Gateway Auth creates a Human Gateway auth session reference. Your app may still create and control its own session, cookie, token, or user access state after your backend verifies the signed callback.

Session model

Human Gateway Auth result
- partner_user_id: stable partner-scoped user reference
- auth_session_id: Human Gateway session reference
- expires_at: Human Gateway session expiration timestamp
- project_id: Human Gateway project context
- verified_human: proof-of-human result
- verification_level: World ID verification level returned for this proof

Partner app session
- created and controlled by the partner
- stores only what the partner needs
- should be granted after valid backend callback verification
- should respect the partner's own logout, expiration, and access rules

Logout and expiration

Partners should define how their own app session expires and how logout behaves. Clearing the partner app session is separate from any Human Gateway session reference you store for audit or reconciliation.

Partner logout example

// Partner logout should clear the partner app session.
// If your integration also tracks Human Gateway auth_session_id,
// reconcile or revoke it according to your product requirements.

await fetch("/api/logout", {
  method: "POST",
});

Recommended UI states

A good Auth integration should handle success, cancellation, popup blocking, backend confirmation, expiration, and logout clearly.

UI states

Recommended UI states
- Signed out
- Opening Human Gateway Auth
- Waiting for proof
- Auth completed
- Waiting for backend confirmation
- Signed in
- User closed popup
- Popup blocked
- Auth failed
- Session expired

Privacy model

Human Gateway Auth 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 may receive scoped operational fields such as verified_human, partner_user_id, auth_session_id, project_id, action information, expiration timestamps, event IDs, and callback timestamps.

verified_human, verification_level, partner_user_id, auth_session_id, project_id, action information, expiration timestamps, event IDs, and callback timestamps.

Human Gateway does not infer, upgrade, or claim a stronger verification level than the value returned by World ID.

Partner responsibilities

Partners remain responsible for their own application account model, session cookies or tokens, authorization logic, user notices, consent flows, callback endpoints, secrets, data retention, and legal compliance.

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

Production checklist

Auth checklist

Auth production checklist
- Create an Auth action in Partner Console
- Use an explicit auth actionKey
- Configure allowed frontend origins
- Configure a full backend callback URL
- Keep callback secrets backend-only
- Launch Auth from a direct user action
- Treat SDK result as immediate UX only
- Verify signed auth.completed callback before granting durable access
- Store callback event_id for idempotency
- Decide how partner_user_id maps to your app user/session model
- Handle session expiration and logout clearly
- Avoid collecting unnecessary personal data

Next steps

For one-time proof-of-human checks, continue with Verify. For installation and basic setup, review the Quickstart.