Build Against The API

Understand the API's authentication families, response expectations, webhook and cron semantics, and the contract details an integration must record before depending on an endpoint.

On this page

API authentication families

Family	Authentication	Caller	Failure behavior
Health	None for liveness; readiness performs a server-side database check.	Load balancer, deployment platform, or monitor.	Return a non-success status when the tested dependency is unavailable.
Public submission	No session required; validated input and route-specific rate limiting.	Contact and waitlist forms.	Reject invalid or abusive input without revealing internal state.
Signed-in customer	Supabase session resolved on the server.	Auth profile, checkout, portal, and billing status clients.	Fail closed when identity, ownership, or feature access is uncertain.
Admin/system	Authenticated profile plus server RBAC and feature access.	Exports, refunds, customer sync, subscription operations, and analytics.	Return an explicit unauthorized or forbidden result and never trust submitted role data.
Provider webhook	Provider-specific signature validation over the expected request payload.	Stripe, Lemon Squeezy, or Resend.	Reject invalid signatures before persistence or business processing.
Scheduled job	Authorization: Bearer with CRON_SECRET.	External scheduler or reviewed platform adapter.	Reject missing and placeholder secrets before rate limiting or job execution.

Implementation reference4 areas

These Product code locations explain how the documented behavior is implemented. Expand them when you are ready to customize or maintain this area.

Route entrypoints

Thin route handlers establish request IDs, parse requests, and delegate to feature services.

src/app/api/billing/checkout/route.ts
src/app/api/contact/route.ts
src/app/api/analytics/platform/range/route.ts

Authentication and result contracts

Shared API guards and result helpers keep failures and request correlation consistent.

src/lib/auth/guards/api.ts
src/lib/api/result.ts

Input schemas

Feature-owned schemas define accepted values and normalization before domain work begins.

src/features/contact/shared/schemas.ts
src/features/billing/server/checkout/request.ts

Route regression tests

Tests document invalid input, authorization, provider failure, and expected response behavior.

src/app/api/contact/__tests__/route.test.ts
src/app/api/billing/checkout/__tests__/route.test.ts

Reference paths are relative to the Shipflash-Product checkout.

Contract worksheet for every endpoint

Record	Required detail
Purpose and owner	The user or system outcome, owning feature, stability, and support status.
Request	Method, path parameters, query parameters, headers, media type, body schema, defaults, and limits.
Identity	Authentication method, role/feature permission, resource ownership, and sensitive-data policy.
Success	Status code, response schema, cache behavior, created or changed state, and asynchronous follow-up.
Failures	Validation, auth, rate limit, conflict, provider, unavailable, and unexpected error shapes.
Reliability	Idempotency key or dedupe identity, retry safety, ordering assumptions, timeout, and partial-failure behavior.
Operations	Request ID, logs, metrics, alerts, dashboards, support lookup fields, and repair path.
Examples	A redacted successful request/response and at least one realistic failure example.

Safe integration checklist

Read the route, delegated service, shared schema, and route tests before writing a client.
Use the exact HTTP method and content type; scheduled publishing is POST while the two cron routes are GET.
Treat non-2xx responses and network timeouts as expected outcomes and preserve the returned request identifier.
Never retry a mutation until its idempotency or deduplication behavior is understood.
Do not expose CRON_SECRET, provider webhook secrets, service credentials, or server-only routes in browser code.
Create an integration test for the contract your product depends on.