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
  • 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 and /deny power advanced consent surfaces.
  • POST /oauth/revoke 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.