Public vs Internal Routes
Route Audience Metadata
Section titled “Route Audience Metadata”ZUTAX marks operations with OpenAPI extensions:
x-zutax-audience:publicorinternalx-zutax-auth: expected auth mode (api_key,jwt,none)
The public schema and docs reference include only public audience routes.
Public Routes
Section titled “Public Routes”Public routes are intended for external integrations and support API key auth.
Representative public resources include:
- parties
- invoices
- credit notes
- dispatches
- directory
- reports
- resources
- webhooks
Internal Routes
Section titled “Internal Routes”Internal routes are JWT-driven operational/admin flows.
Representative internal resources include:
- auth/bootstrap
- workspaces
- tenants management
- users and roles administration
- billing administration
Why This Split Matters
Section titled “Why This Split Matters”- Limits key-based integrations to bounded surface area.
- Keeps high-risk admin operations out of public API key access.
- Enables filtered public OpenAPI generation for partner-facing docs.
Documentation Behavior
Section titled “Documentation Behavior”/docs/api/reference/-> generated from public-only schema.- Internal routes remain visible in backend internal docs (
/docs) but not public docs.