@humanity-org/react-sdk

React-first setup, core components and hooks, authentication flow, and essential usage patterns for the Humanity React SDK.

The @humanity-org/react-sdk is the official React integration for Humanity. It provides pre-built components and hooks for OAuth authentication and credential verification with full Typescript typings — reducing integration time from days to ~30 minutes.

ℹ️ Node requirement: Node 18 or higher.

Installation

npm

npm install @humanity-org/react-sdk

yarn

pnpm

Peer dependencies (install if not already present):

npm install react react-dom

---

Prerequisites

Before integrating, you need a Humanity client ID. Register your application in the Humanity Developer Portal and note your:

• clientId — e.g. hp_xxx

• redirectUri — the OAuth callback URL you registered (e.g. https://yourapp.com/callback)

---

Quick Start

1

Wrap your app with HumanityProvider

Place HumanityProvider at the root of your application. All SDK components and hooks must be rendered inside it.

import { HumanityProvider } from '@humanity-org/react-sdk';

function App() {
  return (
    <HumanityProvider
      clientId="hp_xxx"
      redirectUri="https://yourapp.com/callback"
      environment="production"
    >
      <YourApp />
    </HumanityProvider>
  );
}

2

Add a login button

import { HumanityConnect } from '@humanity-org/react-sdk';

function LoginPage() {
  return (
    <HumanityConnect
      scopes={['openid', 'profile', 'identity:read']}
      onSuccess={(result) => console.log('Logged in!', result)}
    />
  );
}

3

Gate content on verification

import { useAuth, HumanityGate } from '@humanity-org/react-sdk';

function Dashboard() {
  const { user, isAuthenticated, logout } = useAuth();

  if (!isAuthenticated) return <div>Please log in</div>;

  return (
    <div>
      <h1>Welcome, {user?.name}!</h1>
      <HumanityGate preset="ageOver21" fallback={<p>Age verification required</p>}>
        <PremiumContent />
      </HumanityGate>
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

---

Sandbox vs Production

Use environment="sandbox" during development to test without real credentials:

<HumanityProvider
  clientId="hp_xxx"
  redirectUri="http://localhost:3000/callback"
  environment="sandbox"
>
  <App />
</HumanityProvider>

⚠️ Warning: Register separate redirect URIs for sandbox and production in the Developer Portal.

---

Token Storage

The storage prop controls where OAuth tokens are kept:

Value	Security	Persists on refresh
memory	Highest	No
sessionStorage	Medium	No
localStorage	Lower	Yes

memory is the default and recommended for most apps. Use localStorage only if you require persistence and understand the XSS risk (Cross-site Scripting).

---

Next Steps

• Components — full props reference for all 6 components

• Hooks — API reference for all 5 hooks

• Error Handling — typed errors and error boundaries