QuickStart

This guide walks you through a complete Humanity integration using the sandbox environment

ℹ️ Sandbox is a safe testing environment provided by humanity that behaves the same as production, but uses test data instead of real user verification. Your application runs locally or in your own infrastructure and connects to the sandbox API over HTTP.

You’ll use the same API endpoints and SDK methods that you would in production.

When you’re ready to go live, you’ll only need to switch your environment configuration from sandbox to production.

How this Quickstart works

Here’s the flow you are about to implement:

1. Get sandbox credentials from Humanity.

2. Initialize the SDK with your client ID and redirect URL.

3. Redirect a user to Humanity to grant consent, then receive an access token when they return.

4. Use that access token to verify one or more presets (is_human, is_21_plus, etc.).

You’ll complete this loop in less than 10 minutes.

1. Request sandbox access 🪪

Humanity issues a dedicated developer isolated environment holding your app´ s configuration, credentials and test data for every integration - your tenant.

Sandbox works just like production — the same login flow, the same consent step, and the same redirect rules — but with test data.

To request access:

Go to Developer Portal - Sandbox

• Create your app

• Set up your app by selecting

  • Your redirect URIs

  • The presets you expect to request (you can generate them from the Dashboard)

• You will receive:

  • A client ID

  • A developer tenant

• Store the following values securely:

  • clientId → required in every OAuth request

  • redirectUri → must match exactly what Humanity registers

  • scopes / preset keys → preset keys you plan to request

📘 Note

Your welcome packet includes a ready-to-use .env template and example redirect URIs. Use these locally and in CI — no repo cloning required.

2. Install and configure the SDK 📦

npm install @humanity-org/connect-sdk

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

const sdk = new HumanitySDK({
  clientId: process.env.HUMANITY_CLIENT_ID!,
  redirectUri: process.env.HUMANITY_REDIRECT_URI!,
  environment: process.env.HUMANITY_ENVIRONMENT ?? 'sandbox',
  // Optionally provide clientSecret for confidential clients
});

ℹ️

This example assumes a public client (such as a browser-based or mobile app), where secrets cannot be safely stored.

If your application runs on a trusted server (for example, a backend API or server-side app), you can configure Humanity as a confidential client by providing a client secret.

Confidential vs Public clients

Confidential vs Public clients

App type	Client type	Uses clientSecret
Browser SPA	Public	❌ No
Mobile app	Public	❌ No
Next.js backend	Confidential	✅ Yes
API server	Confidential	✅ Yes
Background job / worker	Confidential	✅ Yes

3. Complete the OAuth + preset verification loop 🔗

This is the full integration loop you will use in production:

1. Build a Humanity authorization URL

2. Redirect the user to it

3. Receive the callback → exchange code for tokens

4. Verify presets using those tokens

1. Build the authorization URL This generates a Humanity-hosted URL that your app will redirect the user to.

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

1. Redirect the user to Humanity The user leaves your app and is taken to Humanity to review consent and complete verification.

2. Handle callback → exchange the authorization code After the user completes consent, Humanity redirects them back to the redirect URI you registered during sandbox access.

const token = await sdk.exchangeCodeForToken({
  code: searchParams.get('code')!, // Extract from redirect URL
  codeVerifier,   // Must match the PKCE verifier
});

The codeVerifier must be the same value generated before redirecting the user. If it is missing, expired, or incorrect, the token exchange will fail.

⚠️Avoid these common mistakes: - Forgetting to store codeVerifier between the redirect and callback - Passing a redirect URI that does not match the one registered - Missing required preset scopes during URL construction

1. Verify Presets

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

// Example output (shape depends on preset bundle)
// {
//   is_21_plus: { verified: true, timestamp: "..." },
//   humanity_user: { verified: true, subjectId: "..." }
// }