# SDK Environments & Tooling

Base URLs, auth requirements, feature flags, and operational endpoints.

## 1. Environment matrix

<table><thead><tr><th width="113.02734375">Environment</th><th width="446.16796875">Base URL</th><th>When to use it</th></tr></thead><tbody><tr><td>Sandbox</td><td><code>https://api.sandbox.humanity.org/v2/</code></td><td>Default target for development, QA, and staging. Mirrors production contracts with synthetic data.</td></tr><tr><td>Production</td><td><code>https://api.humanity.org/v2/</code></td><td>Live data. Available once your app passes certification and receives production credentials.</td></tr></tbody></table>

### How to select the environment

You can configure environments in one of two ways:

* Using the SDK (recommended)

If you are using `@humanity-org/connect-sdk`, set the environment when initializing the SDK

```solidity
const sdk = new HumanitySDK({
  clientId: process.env.HUMANITY_CLIENT_ID!,
  redirectUri: process.env.HUMANITY_REDIRECT_URI!,
  environment: 'sandbox', // or 'production'
});
```

* **Using environment variables (raw HTTP or custom clients)**

If you are calling the API directly, configure the base URL via environment variables

```bash
HUMANITY_BASE_URL=https://api.sandbox.humanity.org/v2/
```

> 💡 Note
>
> Humanity is a hosted service and does not run locally.
>
> For development, run your app locally while pointing it at the sandbox API.
>
> If you need to work offline or simulate responses, you can mock the API using the published OpenAPI schema with tools such as [Postman](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/)

## 2. OAuth & Authentication

Humanity uses OAuth to let users grant your application permission to request verification results.

In practice, this means:

* Your app redirects the user to Humanity
* The user reviews consent and completes any required verification
* Your app receives a token that allows it to call preset endpoints

### How authentication works

For browser and mobile applications, Humanity uses a secure redirect-based flow with PKCE.

Backend services can also authenticate using client secrets in trusted environments.

You don’t need to implement OAuth yourself — the SDK and API handle the details — but it helps to understand the basics below.

#### **What you must use**

* **PKCE (`code_challenge_method=S256`)** is required for browser and mobile apps to prevent security leaks.
* **Authorization Code flow** is the primary way to obtain tokens are exchanged for access tokens after the user returns to your app.
* **Client secrets** are used in server-side or backend integrations and should never be exposed to end users.

### **Token types you will use**

| Grant Type           | Use Case                                            | Endpoint            |
| -------------------- | --------------------------------------------------- | ------------------- |
| `authorization_code` | User signs in and grants consent                    | `POST /oauth/token` |
| `refresh_token`      | Extend an existing session without user interaction | `POST /oauth/token` |

### Additional OAuth endpotins (advanced)

* `POST /oauth/authorize/approve` — customize or control consent approval.
* `POST /oauth/authorize/deny` — reject an authorization request.
* `POST /oauth/revoke` — revoke access or refresh tokens.

### Discovery & token verification

Humanity provides public endpoints that help your application verify tokens and integrate with standard OAuth tooling available under `/.well-known/*`:

* `openid-configuration` — standard OIDC metadata
* `jwks.json` — public keys for verifying ID tokens
* `hp-configuration` — Humanity-specific metadata (preset catalog, environment switches)

#### **Recommended environment variables:**

```
HUMANITY_CLIENT_ID=...
HUMANITY_CLIENT_SECRET=...  # confidential clients only
HUMANITY_REDIRECT_URI=https://app.example.com/oauth/callback
HUMANITY_ENVIRONMENT=sandbox
```

> ⚠️ **Common pitfall** \
> \
> Redirect URIs must match your registered list exactly. A different port, protocol, or trailing slash causes authorization failures.<br>
>
> For example, these are considered different:
>
> * <http://localhost:3000/oauth/callback>
> * <http://localhost:3000/oauth/callback/>

## 3. Feature availability & runtime behavior

Humanity enables and rolls out features per application, based on your client ID. This includes:

* Which presets your app can request
* Access to beta or experimental endpoints
* Gradual rollout of new verification flows

**You don’t need to manage feature flags yourself — everything is handled server-side by Humanity.**

### Runtime details to be aware of

When integrating with the Humanity API, there are a few consistent behaviors worth knowing:

* **Idempotency keys**<br>

  Some POST requests return an `idempotency_key`. Reusing this key when retrying the same request ensures the operation is only processed once. This is useful when handling retries caused by network timeouts or transient errors.<br>
* **Timestamps**<br>

  All timestamps returned by the API follow the **ISO-8601** standard in UTC format.

  See: <https://en.wikipedia.org/wiki/ISO_8601><br>
* **Feed cursors**<br>

  Feed endpoints return a cursor (for example, `updatedSince`) that marks the last event your app has processed.

  Store this value and send it with your next request so you only receive new changes, even if your job restarts or runs multiple times.

> 💡 Tip
>
> When retrying a POST request, always reuse the original `idempotency_key` to avoid creating duplicate operations.

## 4. Rate limits & resiliency

To keep the platform reliable for everyone, Humanity applies rate limits per application (client ID). Most apps won’t hit these limits during normal usage, but it’s important to handle them correctly—especially for background jobs and feeds.

### Presets & OAuth requests

These endpoints are designed for user-driven interactions such as login and verification.

* **Burst**: 10 req/s\
  A brief spike in requests caused by a user action. For example, a user signs in and your app verifies several presets at once.
* **Sustained**: 60 req/min\
  Continuous traffic over time, such as many users signing in throughout the minute.<br>

If these limits are exceeded, requests may be temporarily throttled.

### Feeds (`/credentials`, `/authorizations`)

Feeds are meant for background sync, not real-time usage.

* Maximum of **500 items** per page - Large enough to process batches efficiently.
* **2-second minimum delay** before fetching the next window - Prevents aggressive polling while ensuring steady progress.

### Retry guidance

Transient failures (rate limits, timeouts, network issues) are expected in distributed systems.\
When a request fails, retry it carefully to avoid making the situation worse.<br>

* Use **exponential backoff** (max 30 seconds)\
  \
  Space out retries instead of retrying immediately. Example: wait 1s → 2s → 4s → 8s before trying again.
* Honor `Retry-After` headers\
  \
  The API can tell you how long to wait. Using that value is best practice.
* Reuse `idempotency_key` on POST retries\
  \
  This ensures retrying a request does not create duplicate operations

> ⚠️ **Common pitfall**
>
> Not persisting your feed cursor (`updatedSince`) causes missed downstream state changes.

## 5. Operational endpoints

Humanity exposes a small set of operational endpoints that help you monitor the API, verify readiness, and discover environment metadata.

These endpoints are typically used by infrastructure, deployment pipelines, and backend services—not during normal user flows.

<table><thead><tr><th width="349.61328125">Endpoint</th><th>Purpose</th><th>Action</th></tr></thead><tbody><tr><td><code>GET /health</code></td><td>Check that the API process is running and responding. Useful for basic uptime monitoring.</td><td>Is the service up?</td></tr><tr><td><code>GET /ready</code></td><td>Confirm the API and its dependencies are ready to serve traffic. Use this before sending real workload traffic</td><td>Is it safe to send traffic right now?</td></tr><tr><td><code>GET /.well-known/hp-configuration</code></td><td>Humanity-specific metadata such as available presets, OAuth URLs, and environment details.</td><td>What presets, OAuth URLs, and environment settings are available right now?</td></tr><tr><td><code>GET /.well-known/openid-configuration</code></td><td>Standard OAuth/OIDC discovery information used by libraries and tooling.</td><td>How does Humanity’s OAuth/OIDC setup work for clients and libraries?</td></tr><tr><td><code>GET /.well-known/jwks.json</code></td><td>Public keys used to verify token signatures.</td><td>Which public keys should I use to verify Humanity-issued tokens?</td></tr></tbody></table>

> 💡 **Tip** \
> \
> Integrate health and readiness checks into your deployment pipeline to confirm the API is available before sending production traffic.

## **6. Before you go live**

Before switching to production credentials, do a final pass to confirm:

* Your app is pointing at the production environment
* Redirect URIs match what’s registered
* Presets requested by your app are enabled
* Background jobs pick up feed processing where they left off
* Health and readiness checks are in place
* Retries are safe and don’t trigger the same operation twice
* Token verification caches signing keys instead of fetching them on every request