API overview

Everything in the reference tab is powered by the generated OpenAPI.

This reference is sourced from the same OpenAPI document that ships with the SDK and drives Humanity’s public playground. Download it to plug into Postman, Stoplight, or your preferred client.

Download the spec

Same document Mintlify uses to render the interactive playground. You can also request a signed copy from DevRel if you need to pin to a specific version.

Base URLs & auth

Environment	Base URL
Sandbox	https://api.sandbox.humanity.org/v2/
Production	https://api.humanity.org/v2/

All endpoints require HTTPS and bearer tokens. Public clients must follow OAuth 2.1 + PKCE (code_challenge_method=S256). Service-to-service flows can use confidential client credentials where approved.

Resources at a glance

Category	Endpoints	Purpose
OAuth	/oauth/authorize, /oauth/token, /oauth/revoke, /oauth/authorize/*	Issue, exchange, approve/deny, and revoke tokens.
Presets	/presets/{preset_name}, /presets/batch, /consent/presets	Verify Humanity presets individually or in bulk.
Status feeds	/credentials, /authorizations	Poll for credential or authorization changes.
Access control	/access/requests/standard, /access/developer/accept, /access/me	Manage developer onboarding and keys.
Discovery	/.well-known/hp-configuration, /.well-known/openid-configuration, /.well-known/jwks.json	Fetch metadata, OAuth URLs, and JWKS sets.
Health	/health, /ready	Operational probes for load balancers and monitors.

Each page under OAuth & Consent, Feeds & Access, and Discovery & Health maps directly to an OpenAPI operation. Set the server dropdown (sandbox or production) and hit Try it to execute real requests with your bearer token.

Working with the spec

1. Download the JSON file above or fetch it programmatically from https://docs.humanity.app/api-reference/openapi.json.
2. Import it into your API tooling. Popular options:
   • Postman/Insomnia for manual testing
   • Stoplight Studio or VS Code OpenAPI viewers for schema exploration
   • openapi-generator / orval if you need a client in another language
3. Keep an eye on the version field—Humanity increments it whenever contracts change. DevRel announcements include release notes and deprecation windows.

Authentication reminders

All operations require HTTPS and a valid access token. If you call the endpoints outside the SDK:

• Read the OAuth section of the Quickstart to mint tokens with PKCE.
• Send Authorization: Bearer <access_token> headers on every request.
• Provide Humanity-Client-Id (optional) when you need explicit attribution across multiple client IDs.

The OpenAPI security block mirrors these requirements so generators and lint rules can enforce them automatically.