Endpoint map
Use this map to identify the service that owns a request and the trust boundary it expects. Use the generated OpenAPI artifacts for the exact operation, method, parameters, and schemas; a hand-maintained list of every controller method will drift.
How public routing maps to services
The API load balancer routes by host and path. For prefixed services it removes
the product prefix before forwarding, so a public
/management/api/v1/... request reaches a Management API controller whose path
starts at /api/v1/....
| Owner | Public edge route | Main consumers | Trust boundary | Contract |
|---|---|---|---|---|
| Auth | /auth/* | Retail, support, account, and agent sign-in | Firebase ID token for principal routes; JWKS is public | Controller source |
| Merchant API | /merchant/* and default API-host routes | Retail portal, POS clients, approved integrations | Firebase plus Peak authorization; narrow public/callback exceptions | OpenAPI |
| Management API | /management/* | Support portal and approved agents | Firebase plus support/agent Peak authorization and mgmt.* permission | OpenAPI |
| Customer API | /customer/* and selected direct customer routes | Peak Mobile and public customer links | Account Firebase/Peak tokens, or route token plus App Check | OpenAPI |
| AI API | /api/v1/orgs/{orgId}/ai/* | Authorized product experiences | Firebase plus an accepted Peak principal type | OpenAPI |
| Kitchen API | /api/v1/orgs/{orgId}/kitchen/* | Kitchen display clients | Firebase plus merchant Peak authorization | OpenAPI |
| Terminal API | https://terminal.peakpos.co/* | Enrolled POS devices | Device certificate and mutual TLS | OpenAPI |
| Terminal onboarding | /terminal-onboarding/* and terminal-host onboarding routes | New and renewing terminals | Short-lived onboarding credential; internal service identity for approval/renewal operations | OpenAPI |
| Transaction Bundler | /integrations/* | Integration users and provider callbacks | Firebase for authenticated routes; provider-specific callback verification | OpenAPI |
| Status | /status/* | Health monitoring | Intended public health surface only | Controller source |
The edge deployment configuration decides which direct routes reach Customer,
AI, Kitchen, or Merchant API. Do not guess the owner from a shared
/api/v1/orgs/... prefix; confirm it in the table and generated contract.
Auth entry points
Auth has separate principal lanes:
| Lane | Principal routes |
|---|---|
| Merchant | /auth/merchant/me, /auth/merchant/token, /auth/merchant/change-password |
| Support | /auth/support/me, /auth/support/token |
| Agent | /auth/agent/me, /auth/agent/token |
| Account | /auth/account/me, /auth/account/token |
| Token verification | /auth/.well-known/jwks.json |
Authenticated user services normally receive the Firebase ID token in
Authorization and the exchanged Peak token in X-Peak-Authorization.
Firebase App Check, when required, is an additional application-attestation
header and does not replace either user authorization layer.
Public and callback surfaces
Public does not mean unvalidated. These route families deliberately cross the normal user-authentication boundary:
- Merchant invite validation, PIN bootstrap, public wallet/gift-card routes, and provider callbacks.
- Management invite validation/acceptance bootstrap, provider webhooks, and designated lead/demo intake.
- Customer tokenized booking, invoice, review, receipt, and wallet experiences.
- Terminal onboarding poll/certificate operations using the short-lived enrollment token.
- Transaction provider callbacks using the provider's verification mechanism.
- Status and service health checks.
Some public customer routes also require Firebase App Check. Some callbacks use HMAC signatures, OIDC, or provider-specific secrets. Read the service security configuration and controller before changing a matcher; never broaden an exception from one operation to an entire controller prefix.
Authenticated user boundaries
Merchant and retail
Merchant API owns merchant resources and business workflows. Paths commonly
carry {orgId} and {storeId}. The caller must satisfy Firebase
authentication, Peak token type, controller permission, membership, and
resource ownership. The identifiers in the URL are not authorization by
themselves.
Support and agents
Management API owns support-only organization, onboarding, terminal, payment
configuration, and support-user operations. Read and write operations use
different mgmt.* permissions. Agent-accessible controllers also require the
agent token type and declared permission; an agent token is not a blanket
support credential.
Customer accounts
Customer API owns authenticated account experiences and the narrow tokenized public customer surfaces. Account membership does not grant merchant staff or support access.
AI, kitchen, and integrations
AI and Kitchen APIs own their explicit route families even though their paths
begin with the same organization prefix used elsewhere. Transaction Bundler
owns the /integrations edge lane and provider callbacks. Call the owning
service rather than proxying these operations through Merchant API.
Terminal trust boundary
Terminal setup crosses three services:
- Management API creates and confirms the short-lived onboarding token for a terminal selected by support.
- Terminal Onboarding validates the token, accepts the device CSR, and issues the enrollment certificate after confirmation.
- Terminal API serves the enrolled device over mutual TLS for app-check, authentication, checkout, device, sync, and terminal operations.
The onboarding token is not a long-lived terminal credential. After enrollment, device identity is the certificate presented during mutual TLS. Browser Firebase/Peak tokens must not be sent to device-only Terminal API routes.
Internal service boundaries
Internal controllers are intentionally absent from the public OpenAPI inventory. They are used for service-to-service operations such as IAM resolution, scheduled work, token confirmation, certificate renewal, deprovisioning, and downstream writes.
An internal request must pass the owning service's configured controls:
- a Cloud Run service identity token for the expected audience;
- an explicitly allowed calling principal;
- any request-specific internal credential or ownership check.
The path name /internal/v1/... is not protection by itself. Never make these
routes browser-accessible, publish them in a user SDK, or reuse a user, agent,
account, onboarding, or terminal token to call them.
Ownership decision rules
Before wiring a new caller:
- Locate the operation in the owning service's generated OpenAPI contract.
- Confirm how the public host/prefix reaches that service.
- Identify whether the caller is a merchant, support user, agent, account, enrolled terminal, provider callback, or service identity.
- Confirm the service security matcher and controller permission.
- Preserve organization/store membership and resource-ownership checks.
- Use an internal route only from its allowlisted service principal.
When a route moves, update controller ownership, edge routing, security configuration, generated OpenAPI, and every generated client together. Update this service-level map only when the boundary itself changes.