SDK / API Integration Overview

Complete guide to Humanity's API surface, SDK capabilities, OAuth flows, and use cases for web2 authentication and verification.

The Humanity Public Dev API gives developers end-to-end guide for integrating with Humanity’s verification platform

Key Concepts

Understanding three core concepts will help you navigate the API surface:

Presets

Predefined verification checks such as is_human, is_21_plus

Attestations

Signed statements Humanity issues after performing verification (e.g., “government ID verified”, “liveness completed”).

Attestations are the building blocks behind presets.

Evidence payloads

Secure data to derive attestations.

• Presets are the verification questions your application asks.
• Each preset is evaluated using one or more attestations performed by Humanity.
• The result is returned to your application along with an evidence payload that can be audited without exposing raw user data.

┌──────────────────────────────┐
│          Preset              │
│  (What your app asks)        │
│                              │
│  is_human                    │
│  is_21_plus                  │
│  humanity_user               │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│        Attestations          │
│  (What Humanity verifies)    │
│                              │
│  • Liveness completed        │
│  • Government ID verified    │
│  • Age threshold met         │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│        Evidence Payloads     │
│  (What is returned securely) │
│                              │
│  • Timestamps                │
│  • Issuer + signatures       │
│  • Verified attributes       │
└──────────────────────────────┘

---

What you can build

• Verify specific user claims (e.g. age, humanity status).
• Authenticate users and manage consent using OAuth.
• Access validated user identity data.
• Keep systems in sync as authorizations or credentials change.

One common approach is an OAuth-based flow, shown below (similar to Google or Stripe).

┌──────────────────┐
│     Your App     │
└─────────┬────────┘
          │
          │ 1. Redirect user to /oauth/authorize
          ▼
┌──────────────────────────────────┐
│  Humanity OAuth /authorize       │
│  (User sees consent + performs   │
│   required verification)         │
└─────────┬────────────────────────┘
          │ 2. User completes consent
          │    and is redirected back
          ▼
┌──────────────────────────────────┐
│   Redirect Back (your redirect)  │
└─────────┬────────────────────────┘
          │ 3. Exchange authorization code
          ▼
┌──────────────────────────────────┐
│     /oauth/token                 │
│     (Get access token)           │
└─────────┬────────────────────────┘
          │ 4. Call preset endpoint
          ▼
┌──────────────────────────────────┐
│   /presets/<preset_name>         │
│   (e.g., is_human, is_21_plus)   │
└─────────┬────────────────────────┘
          │ 5. Receive verdict / result
          ▼
┌─────────────────┐
│     Your App    │
└─────────────────┘

The example below demonstrates a simple application that uses verified email and connected social accounts to tailor user content:

Personalized Newsletter Demo App

---

When to use the SDK vs the API

Use the API directly for custom integrations, non-TypeScript stacks, or generic OAuth/OIDC clients.

Use the SDK when building Node.js or TypeScript applications that benefit from typed helpers and reduced boilerplate.

Getting started

📦 @humanity-org/connect-sdk	💻 API Reference
A TypeScript SDK for working with the Humanity API	Complete documentation for every API endpoint
@humanity-org/connect-sdk	API Reference