Auth

Sign in verified humans privately.

Human Gateway Auth lets Partners add a verified-human login flow with Project-scoped PartnerUsers and Human Gateway 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. After a successful Auth flow, Human Gateway resolves or creates a Project-scoped PartnerUser and creates a Human Gateway auth session.

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 application sessions, authorization 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 Project-scoped PartnerUser and Human Gateway auth session are useful.

Auth use cases

Good fit for Auth
- Sign in with verified-human proof
- Human-only account access
- Private login without collecting identity documents
- Project-scoped verified-human sign-in and session flows
- 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

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

Frontend environment variables

NEXT_PUBLIC_HG_PROJECT_ID=project_xxx
NEXT_PUBLIC_HG_AUTH_ACTION_KEY=hg_auth_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 Auth Actions, namespace those values locally as described in the SDK guide.

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

Returning auth continuity

For returning Auth, pass the partner_user_id from a previous successful Human Gateway Auth result for the same Project as partnerUserId. Treat this value as an opaque Human Gateway continuity reference.

partnerUserId is only a continuity hint. It does not authenticate the user by itself. Human Gateway independently validates the returning Auth flow and requires continuity with the same Project-scoped PartnerUser before Auth can complete.

Returning auth

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

// partnerUserId is an opaque Human Gateway continuity hint.
// It does not authenticate the user by itself.
// Human Gateway independently validates Auth continuity server-side.

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,
  "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 the opaque Human Gateway PartnerUser reference scoped to this Project.
auth_session_id references the Human Gateway auth session created by the Auth flow.
expires_at indicates when the Human Gateway auth session expires.

Signed callback

After Auth completes, Human Gateway can send a signed auth.completed callback to your backend. Use the server SDK to verify the signature, timestamp, expected Project binding, event consistency, and required auth.completed payload contract before granting durable app access or updating your database.

auth.completed

{
  "event_id": "evt_xxx",
  "event": "auth.completed",
  "success": true,
  "verified_human": true,
  "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;

  // payload is fully validated and typed as auth.completed.
  // 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

Keep the trusted Project ID and its matching Project callback secret together in server-side configuration. For multi-Project integrations, namespace each trusted pair locally and validate the callback with expectedProjectId.

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 }) for first Auth, or includes partnerUserId from a previous successful Auth result for the same Project.
3. The SDK launches the Human Gateway Auth flow for that Project and Action.
4. User completes the required proof-of-human flow.
5. Human Gateway resolves or creates the Project-scoped PartnerUser and creates a Human Gateway auth session.
6. Partner frontend receives an immediate UX result.
7. Human Gateway sends a signed backend callback.
8. Partner backend verifies the callback against the trusted Project configuration.
9. Partner stores or reconciles partner_user_id as the opaque Human Gateway user reference for that Project.
10. Future returning Auth may send that same Project-scoped partner_user_id back as partnerUserId to request continuity.
11. Partner grants app access according to its own session model.

Session model

Human Gateway Auth creates a Human Gateway auth session for the Project-scoped PartnerUser. Your application may separately create and control its own session, cookie, token, or access state after your backend verifies the signed callback.

Session model

Human Gateway Auth result
- partner_user_id: stable opaque PartnerUser reference scoped to the Project; it may later be supplied as partnerUserId for returning Auth continuity in that same Project
- auth_session_id: Human Gateway auth session reference
- expires_at: Human Gateway auth session expiration timestamp
- project_id: Human Gateway Project context
- verified_human: proof-of-human result

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.

partner_user_id is the opaque PartnerUser reference for the current Project. Returning Auth may pass that same Project-scoped value as partnerUserId. It is a continuity hint, not authentication evidence, and Human Gateway validates the returning Auth flow independently before completion.

Human Gateway does not expose internal World session identifiers, internal World identity references, or internal persistence links used to maintain that continuity.

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
- Validate the expected Project with expectedProjectId
- Store callback event_id for idempotency
- Treat partner_user_id as the opaque PartnerUser reference for its Project
- 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.