> ## Documentation Index
> Fetch the complete documentation index at: https://humanity-eaeda8f6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Request sandbox access" icon="id-card-clip">
    1. Reach out to `devrel@humanity.app` 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

    <Callout>
      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.
    </Callout>
  </Step>

  <Step title="Install and configure the SDK" icon="cube">
    ```bash theme={null}
    npm install @humanity-org/connect-sdk
    ```

    ```ts theme={null}
    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.
  </Step>

  <Step title="Complete the OAuth + preset verification loop" icon="link">
    ```ts theme={null}
    // 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'],
    });
    ```

    <Tip>
      Prefer calling the HTTP endpoints directly? Mirror the same flow with [`/oauth/*`](/api-reference/endpoint/oauth-authorize) and [`/presets/batch`](/api-reference/endpoint/presets-batch) using the same base URLs and bearer tokens.
    </Tip>
  </Step>
</Steps>

## Where to go next

* Review [OAuth Scopes](/concepts/scopes) to understand the scope-based authorization model.
* Review [Environments & tooling](/development) for base URLs, feature flags, and health probes.
* Browse the [SDK guide](/sdk/overview) for advanced helpers like consent polling and status feeds.
* Try the [Query Engine](/api-reference/endpoint/queries-evaluate) for declarative credential queries.
* Explore the [full API reference](/api-reference/introduction) to see schemas, examples, and autogenerated snippets.