OpenAPI Specification

The HumanAuth Platform API publishes a hand-written, validated OpenAPI 3.1 specification. Use it to codegen typed clients in any language — Python, Go, Java, Ruby, Rust, C#, PHP, and more — in minutes.

Download

https://api.humanauth.ai/openapi.json — live JSON (production).
spec.yaml on GitHub — raw YAML source.

The spec is also served from local dev (http://localhost:8787/openapi.json) when you run pnpm --filter @humanauth/platform dev.

Codegen examples

Python (`openapi-generator-cli`)

openapi-generator generate \
  -i https://api.humanauth.ai/openapi.json \
  -g python \
  -o ./humanauth-py

Go (`oapi-codegen`)

oapi-codegen \
  -package humanauth \
  -generate types,client \
  https://api.humanauth.ai/openapi.json \
  > humanauth/client.go

TypeScript (`openapi-typescript`)

npx openapi-typescript \
  https://api.humanauth.ai/openapi.json \
  -o ./humanauth.d.ts

(For TypeScript projects, prefer the native @humanauth/sdk which ships with handcrafted types, runtime helpers, and webhook signature verification.)

Java / Kotlin / Ruby / Rust / etc.

openapi-generator-cli supports 50+ targets:

openapi-generator generate \
  -i https://api.humanauth.ai/openapi.json \
  -g <target>          # java | kotlin | ruby | rust | csharp | php | ...
  -o ./humanauth-client

See the openapi-generator language list for the full set.

Browse interactively

You can open the spec in any OpenAPI viewer:

Swagger Editor
Stoplight Studio
Redoc CLI (redocly preview-docs https://api.humanauth.ai/openapi.json)

Most editors will render the operations, schemas, examples, and authentication schemes from the spec directly.

What’s covered

30 endpoints across health, discovery (JWKS, OpenAPI), authentication, devices, sessions, humans, groups, authorize, requests, receipts (v1 + v2), reports, webhook subscriptions, and live peer-status SSE.
4 authentication schemes — apiKey (tenant API key), workosJwt (user identity), deviceProof (device-bound signature), deviceId (mobile rogue-report header).
Receipt v2 (JWS) — full schema, including the ha.{action, plan_hash, plan_alg, approvers} claims that verifier SDKs (any language) validate offline against the JWKS at /.well-known/jwks.json.
Webhook events — request.decided, request.reported, webhook.test. Each documents the X-HumanAuth-Signature, X-HumanAuth-Event-Id, X-HumanAuth-Delivery-Id headers and the expected WebhookEnvelope body.
PII discipline — examples use synthetic identifiers (alice@example.com, ten_acme, req_xxx). Sensitive fields like device push tokens are omitted from response schemas.

Versioning policy

info.version in the spec matches the platform’s package version. The HumanAuth Platform follows semver in spirit:

Patch / Minor releases — non-breaking additions (new fields, optional parameters, new endpoints). Existing integrations keep working without code changes. Old fields are preserved indefinitely.
Major releases (/v2/...) — breaking changes are introduced as a parallel API path. The existing /v1/... surface is kept stable for at least 12 months after a new major ships, with explicit deprecation notices in the spec (deprecated: true).

The current API surface is /v1/*. A future /v2/* would mean we introduced a breaking change somewhere — but the spec would carry both versions during the overlap.

Anti-drift guarantee

A CI check (coverage.test.ts) walks every router.<method>(...) call in packages/platform/src/routes/*.ts and asserts each is documented in spec.yaml. If a developer adds a new route and forgets to update the spec, the build fails. The spec is never stale.

Internal endpoints

A small number of endpoints are marked with x-internal: true (e.g. POST /webhooks/workos, consumed by WorkOS). These are documented for completeness but are NOT part of the public integration surface — your integrations should not call them.