Humanity SDK

1. About humanity-org/connect-sdk

The @humanity-org/connect-sdk package is the official TypeScript integration layer for Humanity’s Public API.

2. Common SDK use cases

Use @humanity-org/connect-sdk if you are building a Node.js or TypeScript application and want:

• Typed helpers instead of raw HTTP calls

• Built-in handling for OAuth, PKCE, and preset verification

• Safer defaults for retries, errors, and token handling

3. How to install

npm install @humanity-org/connect-sdk
# or
yarn add @humanity-org/connect-sdk
# or
pnpm add @humanity-org/connect-sdk

import { HumanitySDK } from '@humanity-org/connect-sdk';

4. Initialization & configuration

Option	Required	Description
clientId	✅	Issued when your app is approved.
redirectUri	✅	Must match one of the URIs registered with Humanity.
environment	➖	sandbox or production. Sets the Humanity base URL automatically (defaults to sandbox).
baseUrl	➖	Advanced override for regional/private deployments (takes precedence over environment).
clientSecret	➖	Only required for confidential clients or service-to-service flows. Never ship it to the browser.
clockToleranceMs	➖	Adjusts token expiry validation for skewed environments.

Example: Local or serverless project

const sdk = new HumanitySDK({
  clientId: process.env.HUMANITY_CLIENT_ID!,
  redirectUri: process.env.HUMANITY_REDIRECT_URI!,
  environment: process.env.HUMANITY_ENVIRONMENT ?? 'sandbox',
  clientSecret: process.env.HUMANITY_CLIENT_SECRET, // optional
});

Create a new SDK instance per request (common in serverless), or reuse a shared instance and pass tokens as needed—choose what fits your runtime. Store secrets in your platform’s secret manager and never include them in client-side code.

Developer guidance

• Frontend apps → do not set clientSecret.

• Backend apps → may use clientSecret for confidential flows.

• Serverless → create a new SDK instance per request (stateless).

• Node server → initialize once and pass tokens into helpers as needed.

💡 Tip

Always store credentials in a secrets manager—never commit them to source control.

5. OAuth helpers

These helpers implement the full OAuth redirect flow: redirecting the user to Humanity, exchanging the authorization code, and managing tokens.

Build the authorization URL

const { url, codeVerifier, state } = sdk.buildAuthUrl({
  scopes: ['is_human', 'is_21_plus'],
  prompt: 'consent',
});

Redirect the user to url. When Humanity calls back with ?code=..., exchange it

const token = await sdk.exchangeCodeForToken({
  code: callbackQuery.get('code')!,
  codeVerifier, // must match the one from buildAuthUrl
});

Token revocation

await sdk.revokeToken({
  token: token.refreshToken,
  tokenType: 'refresh_token',
});

ℹ️ Store codeVerifier and state temporarily (for example, in a session or HTTP-only cookie) and reuse them when handling the callback.

6. Preset verification

Call preset verification after you have an access token—typically right after sign-in or when gating a sensitive action.

const presets = await sdk.verifyPresets({
  accessToken: token.accessToken,
  presets: ['is_human', 'is_21_plus'],
});

Available helpers include:

• verifyPreset

• verifyPresets

• getPreset

Each maps directly to /presets/*.

Developer notes

• Responses include verification outcomes and safe evidence metadata.

• The SDK normalizes return types so you can write stable application logic.

• Errors propagate as typed HumanitySDKError objects (see below).

7. Using the generated client directly

The generated sdk.client exposes every API endpoint exactly as defined in the OpenAPI specification. Both the SDK helpers and the raw client share the same authentication and transport logic

const preset = await sdk.client.presets.getPreset('humanity_user', {
  headers: { Authorization: `Bearer ${token.accessToken}` },
});

Why this is useful

• For advanced edge cases

• For writing internal abstractions

• For accessing controllers not wrapped by the SDK

• For debugging or prototyping low-level requests

The SDK and API reference regenerate from the same DTOs (src/contracts), TypeScript will always warn you about breaking changes before deploy time.

8. Error handling

All SDK helpers throw structured errors so you can distinguish between user errors, rate limits, and server issues.

You can inspect:

• error.status — HTTP status

• error.code — Humanity error code

• error.details — structured error metadata

try {
  await sdk.verifyPresets({ accessToken, presets: ['is_human'] });
} catch (err) {
  if (err instanceof HumanitySDKError) {
    console.error(err.status, err.code, err.details);
  }
}

9. Before You Ship to Production

A final checklist for production readiness:

• The PKCE flow works end-to-end across all supported browsers

• Redirect URIs are registered for both sandbox and production

• Preset scopes requested by the app are enabled and verified

• Error cases are handled gracefully (expired tokens, revoked access, etc.)

• Retries are safe and don’t create duplicate actions

• Advanced use cases using the raw client have been validated

• The build and deployment pipeline points to the production environment