API integration overview

The API reference publishes the same OpenAPI 3.1 document used to generate the repository's typed client. It covers the consumer and administrator application APIs; it is not an unauthenticated public payment API.

Start here

1. Choose the consumer or administrator realm. A token issued for one realm is rejected by the other.
2. Obtain a short-lived Privy access token through the corresponding application.
3. Bootstrap the session with PUT /v1/consumer/session or PUT /v1/admin/session.
4. For consumer requests, discover active memberships with GET /v1/consumer/organizations and use the returned organization ID in organization-scoped paths.
5. Add Idempotency-Key and exact-version fields whenever the selected endpoint declares them.

The hosted API base URL is https://api-production-2c86.up.railway.app. Local development uses http://localhost:4000.

curl --fail-with-body \
  https://api-production-2c86.up.railway.app/health/live

Protected request shape:

curl --fail-with-body \
  -H "Authorization: Bearer $AETHER_ACCESS_TOKEN" \
  https://api-production-2c86.up.railway.app/v1/consumer/organizations

Never place access tokens in source control, documentation, screenshots, URLs, or support messages.

Contract and client

• Browse every operation in the API reference.
• Download the machine-readable OpenAPI document.
• The repository's @workspace/api-client package generates TypeScript types from this exact document.
• Route authentication, organization access, roles, validation, and payment policy are enforced by the API even when a caller bypasses the product UI.