API Standards¶
Status: Proposed baseline
API surfaces¶
/api/public/v1/...— managed/custom public experiences./api/tenant/v1/...— tenant console and tenant operations./api/platform/v1/...— platform operators only./webhooks/...— provider callbacks with provider-specific verification.
Custom/headless access is permitted only for tenants under a Custom contract even when endpoints are technically part of the public API surface.
Contract rules¶
- OpenAPI 3.1 is the canonical HTTP contract format.
- UUID/ULID-style opaque identifiers; no sequential IDs exposed as an authorization mechanism.
- RFC 3339 timestamps in UTC; tenant locale/timezone only for presentation and local business-rule interpretation.
- Monetary values transmitted as integer minor units plus ISO currency where applicable.
- Cursor pagination for large collections.
- Structured error envelope with stable error codes.
Idempotency-Keyrequired for payment/booking/order/quote-acceptance operations that can create financial or inventory side effects.- Optimistic concurrency/version field for high-conflict administrative resources where needed.
- Request correlation ID returned and logged.
- BCP 47 locale identifiers for explicit locale parameters/metadata.
- Locale resolution/fallback must be deterministic for localized resources; APIs must not infer currency or timezone from locale.
Example error envelope¶
{
"error": {
"code": "AVAILABILITY_CONFLICT",
"message": "The selected resource is no longer available.",
"details": {},
"requestId": "..."
}
}
Compatibility¶
Breaking API changes require a new major API version or an explicitly managed migration window. Internal module contracts may evolve faster but must retain test coverage at engine boundaries.
Internationalization contract¶
Public/headless APIs may negotiate locale through documented route/query/header mechanisms. When fallback materially affects a localized response, the contract must be able to expose requested vs resolved locale and whether fallback occurred.
Canonical timestamps remain RFC 3339/UTC at API boundaries unless a domain-specific local-time contract is explicitly required. Operational schedules retain their authoritative IANA timezone separately. Currency amounts remain minor-unit + ISO currency values independent of locale formatting.
Authentication contract — I1-B4¶
Human clients authenticate through Keycloak using OIDC Authorization Code + PKCE.
Password/direct-grant and implicit browser flows are not supported.
API authorization must treat OIDC tokens as authentication evidence, not as the authoritative store for tenant memberships, role scopes or commercial entitlements.
Security-sensitive token claims such as issuer, audience, subject, expiry and assurance/session context are validated according to the client/API surface.
Machine clients use OAuth 2.0 Client Credentials and are mapped to application-owned client/scope records.
Provider webhooks use provider-specific signature verification.
Identity context¶
The authenticated User is resolved from the validated external identity mapping:
issuer + subject -> Touriffique User
Tenant context is resolved separately from trusted request/site/membership/client context and must still satisfy the tenant-isolation contract.
Email address is never an authorization identifier.