@humanity-org/react-sdk

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

Not building in React, or need full OAuth control? → @humanity-org/connect-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 install @humanity-org/react-sdk
# or
yarn add @humanity-org/react-sdk
# or
pnpm add @humanity-org/react-sdk

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)

---

Getting started

Step 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={process.env.HUMANITY_CLIENT_ID!}
      redirectUri={process.env.HUMANITY_REDIRECT_URI!}
    >
      {/* rest of your app */}
    </HumanityProvider>
  );
}

Step 2 — Add a login button

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

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

Step 3 — Gate content on verification

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

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

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

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

---

Sandbox vs Production

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

<HumanityProvider
  clientId="app_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).

---

Need integration examples?. Head to react-sdk-examples