Quickstart

Launch an end-to-end Humanity flow in three steps.

You can stand up a complete sandbox integration by following the steps below. Everything mirrors production contracts, so promoting to live just means pointing at the production base URL.

1. Request sandbox access

   1. Reach out to [e-mail] with your organization name, redirect URIs, and required presets.
   2. We provision a developer tenant, client ID, and optional shared test token for Appendix D flows.
   3. Record the following secrets securely:
      • clientId (required in every OAuth request)
      • redirectUri (must match what you registered)
      • scopes / preset keys you plan to request

   The welcome packet you receive after onboarding includes a ready-to-fill .env template plus example redirect URIs. Use those values locally and in CI—nothing from this repository is 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
   });
   

   Behind the scenes the SDK wraps the generated REST client, so every method maps one-to-one with the OpenAPI operations you see in the reference tab.

3. Complete the OAuth + preset verification loop

   // Generate state for CSRF protection
   const state = HumanitySDK.generateState();
   
   const { url, codeVerifier } = sdk.buildAuthUrl({
     // Request OAuth scopes - see /concepts/scopes for the full list
     scopes: ['identity:read', 'identity:date_of_birth', 'kyc:read'],
     state, // Pass state in - buildAuthUrl does NOT return it
     additionalQueryParams: { prompt: 'consent' },
   });
   
   // 1. Store state + codeVerifier server-side, then redirect user to `url`.
   // 2. When Humanity calls back, verify state matches, then exchange the code:
   const token = await sdk.exchangeCodeForToken({
     code: searchParams.get('code')!,
     codeVerifier,
   });
   
   // 3. Verify presets with either the SDK helper or the raw API
   const results = await sdk.verifyPresets({
     accessToken: token.accessToken,
     presets: ['age_over_21', 'is_human', 'kyc_passed'],
   });
   

   Prefer calling the HTTP endpoints directly? Mirror the same flow with /oauth/* and /presets/batch using the same base URLs and bearer tokens.

Where to go next

• Review OAuth Scopes to understand the scope-based authorization model.
• Review Environments & tooling for base URLs, feature flags, and health probes.
• Browse the SDK guide for advanced helpers like consent polling and status feeds.
• Try the Query Engine for declarative credential queries.
• Explore the full API reference to see schemas, examples, and autogenerated snippets.