Documentation

Quick start

npm install humad-sdk @worldcoin/idkit

import { HumanAuth } from "humad-sdk/react";

function VerifyButton() {
  return (
    <HumanAuth
      appId="app_your_world_id"
      apiKey="ha_your_key"
      action="login"
      onVerified={(r) => console.log(r.nullifier_hash, r.is_new_user)}
      onError={(e) => console.error(e)}
    />
  );
}

Login with Humad (OIDC)

Standards-compliant OAuth 2.1 + OpenID Connect. PKCE-required for public clients, client_secret_post / client_secret_basic for confidential clients, RS256-signed id_tokens, refresh token rotation, RP-Initiated Logout.

1. Register an OAuth client

Go to /dashboard/oauthand create a client. You'll need at minimum a name and one redirect_uri. For SPAs, also set post_logout_redirect_uris.

• Public client (SPA / mobile): no client_secret; PKCE is enforced.
• Confidential client (server-side): store client_secret in your backend; PKCE still recommended.
• Scopes: openid (required), profile, verified_human, email, offline_access (for refresh tokens).

You can later edita client's name / homepage / redirect_uris / scopes from the dashboard (the client_id and client_type stay frozen). Confidential clients also expose a Rotate secret button — handy when a secret leaks; the old secret stops working immediately, so coordinate with your RP deploy.

2. Browser flow

import { signIn, handleCallback, getUser } from "humad-sdk";

// On your "Login with Humad" button:
await signIn({
  clientId: "ha_oauth_xxxxxxxx",
  redirectUri: "https://yourapp.com/oauth/callback",
  scopes: ["openid", "profile", "verified_human"],
});

// On /oauth/callback:
const { tokens } = await handleCallback({ clientId: "ha_oauth_xxxxxxxx" });
const user = await getUser(tokens);

// user.sub                  — stable, pairwise user id (string)
// user.handle               — Humad handle (e.g. "alice")
// user.verified_human       — boolean
// user.verification_level   — "orb" | "device" | "phone"

3. Server flow (confidential client)

import { exchangeCodeForTokens, getUserInfo } from "humad-sdk";

// In your /oauth/callback route handler:
const tokens = await exchangeCodeForTokens({
  clientId: process.env.HUMAD_CLIENT_ID!,
  clientSecret: process.env.HUMAD_CLIENT_SECRET!,
  code,
  codeVerifier,
  redirectUri,
});

const user = await getUserInfo({ accessToken: tokens.accessToken });

Silent refresh

Access tokens expire in 15 minutes. Pick the helper that matches your security posture.

(a) Background timer — if you can store the refresh_token

import { startAutoRefresh } from "humad-sdk";

const controller = startAutoRefresh({
  clientId: "ha_oauth_xxxxxxxx",
  initialTokens: tokens,
  onUpdate: (next) => setTokens(next),   // persist the rotated tokens
  onError: (err) => console.warn(err),   // refresh failed — fall back to signIn()
  refreshLeewaySec: 60,                  // renew 60s before exp
});

// later (sign out / unmount):
controller.stop();

(b) iframe + prompt=none — if you can't safely hold a refresh_token

import { silentRenew, handleSilentCallback } from "humad-sdk";

try {
  const { tokens: next } = await silentRenew({
    clientId: "ha_oauth_xxxxxxxx",
    redirectUri: "https://yourapp.com/oauth/callback",
  });
  setTokens(next);
} catch (err) {
  // SSO expired or interaction required — fall back to signIn()
}

// On /oauth/callback, handle BOTH normal and silent iframe results:
const wasSilent = await handleSilentCallback({ clientId });
if (!wasSilent) {
  const { tokens } = await handleCallback({ clientId });
  // ... normal post-login flow
}

Silent renew relies on the Humad SSO cookie. If the user has been inactive long enough for the SSO session to expire, the iframe will time out and you must initiate a regular signIn().

Logout

Two flavors, depending on whether you want to keep the Humad SSO session alive across other RPs.

(a) Quiet token revocation — default

Invalidates the user's tokens for your app. The Humad SSO session continues, so the user stays signed in to other RPs.

import { signOut } from "humad-sdk";

await signOut({
  token: tokens.refreshToken!,
  tokenTypeHint: "refresh_token",
  clientId: "ha_oauth_xxxxxxxx",
});

(b) RP-Initiated Logout — end the SSO session

Ends the user's Humad SSO session and redirects back to your post-logout page. Use this for a real "sign out everywhere" UX. Requires post_logout_redirect_uri to be pre-registered on the client.

await signOut({
  mode: "navigate",
  clientId: "ha_oauth_xxxxxxxx",
  idTokenHint: tokens.idToken,
  postLogoutRedirectUri: "https://yourapp.com/goodbye",
  state: "csrf-token-or-return-marker",
});

Need a URL only (e.g. for an <a href>)? Use buildEndSessionUrl(...). The endpoint follows OIDC RP-Initiated Logout 1.0.

Verify API

Direct REST access if you don't want to use the SDK. Use this when you only need one-shot human verification (CAPTCHA-replacement) and don't need user sessions.

x-humanauth-key: ha_your_api_key

{
  "proof": "0x...",
  "merkle_root": "0x...",
  "nullifier_hash": "0x...",
  "action": "login",
  "verification_level": "orb"   // optional
}

{
  "success": true,
  "nullifier_hash": "0x...",
  "is_new_user": true,
  "action": "login"
}

{ "action": "login" }   // optional, defaults to "humanauth-verify"

{
  "rp_context": {
    "rp_id": "app_xxx",
    "nonce": "...",
    "created_at": 1234567890,
    "expires_at": 1234567890,
    "signature": "0x..."
  }
}

Apps API

OIDC discovery

Most OIDC client libraries can configure themselves from the discovery document.

https://humanauth.vercel.app/.well-known/openid-configuration

Note on domains: the IdP issuer currently lives at humanauth.vercel.app as a placeholder. A humad.*custom domain will be assigned later. The SDK reads the issuer URL from discovery, so SDK consumers won't see a breaking change. If you hardcode issuer in your config, plan a one-line update.

Concepts

Operational notes

{
  "ok": true,
  "service": "humanauth",
  "env": "production",
  "sha": "ab12cdef",
  "durationMs": 42,
  "checks": {
    "db":   { "ok": true, "durationMs": 38 },
    "jwks": { "ok": true, "durationMs": 4  }
  }
}