API reference

Use this page to choose the correct service boundary, credential, and generated contract before integrating with a Peak API. The generated OpenAPI artifacts are the route and schema source of truth; this page explains how those contracts are exposed and secured.

Choose the service boundary

The external load balancer removes the product prefix before forwarding a request to most services. Controller paths therefore usually begin with /api/v1 even when the public request begins with /merchant, /management, or /integrations.

Service	Public entry point	Primary callers	Normal credential
auth	/auth/*	Retail, support, account, and agent sign-in flows	Firebase ID token; token-exchange routes return a Peak authorization token
merchant-api	/merchant/* and the default API host routes	Retail portal, POS clients, and approved server integrations	Firebase ID token plus a Peak authorization token
management-api	/management/*	Support portal and approved agents	Firebase ID token plus a support or agent Peak authorization token
customer-api	/customer/* and selected public customer routes	Peak Mobile and tokenized customer experiences	Account Firebase and Peak tokens, or the route-specific public token and App Check
ai-api	/api/v1/orgs/{orgId}/ai/*	Authorized merchant, support, and account experiences	Firebase ID token plus the matching Peak authorization token
kitchen-api	/api/v1/orgs/{orgId}/kitchen/*	Kitchen display clients	Firebase ID token plus a merchant Peak authorization token
terminal-api	https://terminal.peakpos.co/*	Enrolled POS devices	Device certificate and mutual TLS
terminal-onboarding	/terminal-onboarding/* and the terminal host's onboarding routes	New or renewing terminals	Short-lived onboarding credential; internal operations use service identity
tx-bundler	/integrations/*	Authorized integration users and provider callbacks	Firebase for user routes; callback-specific verification for provider routes
status	/status/*	Operational health checks	No user credential; expose only the intended health surface

An endpoint's own security configuration and controller annotations remain authoritative. Public invite, webhook, wallet, or onboarding routes are narrow exceptions to the normal service credential, not evidence that the rest of a service is public.

Build an authenticated request

Most user-facing authenticated requests have two layers:

1. Send the Firebase ID token in Authorization: Bearer <firebase-id-token>.
2. Exchange it through the matching /auth/{tenant}/token route.
3. Send the returned token as X-Peak-Authorization: Bearer <peak-authorization-token>.

The Peak token carries the tenant and authorization context used by the downstream service. It does not replace Firebase authentication. A route that requires Firebase App Check also expects X-Firebase-AppCheck; App Check is application attestation, not user authorization.

Terminal device routes are a different trust boundary. They use the enrolled device certificate over mutual TLS. Internal routes use Cloud Run service identity, audience checks, and explicit principal allowlists. Never forward a user or terminal credential to an /internal/ route.

Canonical generated contracts

Read the checked-in contract that matches the service:

• AI API OpenAPI
• Customer API OpenAPI
• Kitchen API OpenAPI
• Management API OpenAPI
• Merchant API OpenAPI
• Terminal API OpenAPI
• Terminal onboarding OpenAPI
• Transaction bundler OpenAPI

The private documentation site renders browsable references for Merchant, Management, Terminal, Terminal Onboarding, and Transaction Bundler from these same files. The Auth and Status services do not currently publish checked-in OpenAPI artifacts.

Generated contracts intentionally omit internal controllers. A localhost server URL in a checked-in artifact is generation metadata, not a production base URL. The edge routes in the table above are the deployment boundary.

Change or verify a contract

Do not hand-edit an artifact to make documentation pass.

1. Update the service controller, DTO, validation, and OpenAPI annotations.

2. Regenerate the checked-in artifacts:

   bazel run //scripts:sync_openapi_specs

3. Review the artifact diff for the intended path, operation, parameters, response schemas, and security declaration.

4. Regenerate affected SDKs through the repository OpenAPI generator workflow.

5. Run the contract drift gate:

   ./scripts/test-local.sh contracts

The drift gate checks controller coverage and generated client consistency. Route summaries copied into support runbooks are not a substitute for these artifacts.