Environments & Tooling

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

1. Environment matrix

Environment	Base URL	When to use it
Sandbox	https://api.sandbox.humanity.org/api/v1	Default target for development, QA, and staging. Mirrors production contracts with synthetic data.
Production	https://api.humanity.org/api/v1	Live data. Available once your app passes certification and receives production credentials.

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

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

HUMANITY_BASE_URL=https://api.sandbox.humanity.org/api/v1

💡 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

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.

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

  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.

• Timestamps

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

  See: https://en.wikipedia.org/wiki/ISO_8601

• Feed cursors

  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.

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.

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

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

💡 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