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

# Environments & tooling

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

## Environment matrix

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

Set the SDK `environment` option or `HUMANITY_BASE_URL`/`HUMANITY_ENVIRONMENT` env vars in your application to switch between these hosts. Humanity does not expose a public “local” server; if you need offline testing, stub the HTTP calls in your codebase or use the OpenAPI schema with a mocking tool.

## OAuth & authentication

* OAuth 2.1 with PKCE (`code_challenge_method=S256`) is required for browser/mobile apps.
* Token grants:
  * `authorization_code` – exchanged via [`POST /oauth/token`](/api-reference/endpoint/oauth-token)
  * `refresh_token` – same endpoint with the refresh grant body
* Confidential or service-to-service clients receive a `client_secret` and may use HTTP Basic auth with the token endpoint (subject to contract).
* Session helpers:
  * [`POST /oauth/authorize/approve`](/api-reference/introduction) and `/deny` power advanced consent surfaces.
  * [`POST /oauth/revoke`](/api-reference/endpoint/oauth-token) revokes access/refresh tokens when a user withdraws consent.
* JWKS + discovery documents live under `/.well-known/*` so you can validate ID tokens or dynamically discover URLs.

Recommended environment variables:

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

## Feature flags & configuration

* Humanity enables features (new preset catalogs, beta endpoints) per client ID. You will receive flag descriptions in your onboarding packet—no repo changes required.
* API responses include `idempotency_key` echoes on POSTs. Reuse the key when retrying to avoid duplicate actions.
* All timestamps are ISO-8601 strings in UTC. Persist the `updatedSince` cursor returned by feed endpoints to resume polling safely.

## Rate limits & resiliency

* **OAuth & presets:** burst up to 10 requests/second, sustained 60 requests/minute per client ID.
* **Feeds (`/credentials`, `/authorizations`):** page in batches of ≤500 items and wait at least 2 seconds before refetching the next window.
* **Retry guidance:** use exponential backoff capped at 30 seconds and honor `Retry-After` headers on `429` responses.
* **Idempotency:** POST bodies accept optional `idempotency_key` fields (see schemas in the OpenAPI). Reuse keys on network retries.

## Operational endpoints

| Endpoint                                | Purpose                                                                                                 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `GET /health`                           | Liveness with version + git SHA. Ideal for monitoring job schedulers before calling business endpoints. |
| `GET /ready`                            | Readiness check that fans out to downstream dependencies. Use for fail-fast probes.                     |
| `GET /.well-known/hp-configuration`     | Humanity-specific metadata (preset catalog, OAuth URLs, environment switches).                          |
| `GET /.well-known/openid-configuration` | Standard OIDC discovery document.                                                                       |
| `GET /.well-known/jwks.json`            | JWKS set for verifying ID tokens.                                                                       |

Integrate these probes and discovery docs into your monitoring stack before promoting workloads to production.