API Overview
Mabble Helix exposes two tiers of API surfaces: public (no authentication, hostname-routed) and authenticated (capability-token or session-cookie secured).
Surface tiers
Public API — /public/v1/*
These endpoints handle consumer-facing operations that require no authentication. Tenant identity is resolved exclusively from the HTTP Host header — there is no way to supply a tenant ID via query parameters or request body. This design prevents cross-tenant data access from being possible even if the client is compromised.
Base URL: https://<tenant-custom-domain>/public/v1/
Current public endpoints:
| Method | Path | Description |
|---|---|---|
GET | /public/v1/privacy/dsar | Render the DSAR submission form (HTML) |
POST | /public/v1/privacy/dsar/submit | Submit a DSAR |
GET | /public/v1/privacy/notice | Fetch the current published privacy notice (HTML) |
GET | /public/v1/privacy/notice/v:version | Fetch a specific historical privacy notice version (HTML) |
See Public Endpoints Reference for full details.
Authenticated API
Authenticated endpoints require a valid Helix session (HTTP-only session cookie) or a capability token. Capability tokens are server-side only — they must never be sent to or stored in a browser.
Authenticated surfaces include:
- DSAR operator management (list, assign, fulfill, close requests)
- Privacy notice management (draft, publish, version history)
- Tenant configuration (domain routing, theme config, jurisdiction settings)
- Audit log query and digest verification
- User and role management (RBAC)
- Vault record operations
Documentation for the authenticated API is available in the internal operator console at /console/docs. Access requires a tenant administrator session.
Authentication model
Session-based (console users)
Operator console sessions use HTTP-only, SameSite=Strict cookies. Multi-factor authentication (TOTP / WebAuthn passkey) can be enforced per-tenant policy.
Capability tokens (server-to-server)
For machine-to-machine integrations, operators issue capability tokens scoped to specific operations. Key properties:
- Tokens are opaque, short-lived JWTs signed by Helix.
- Tokens are never sent to browsers — this is a hard architectural constraint.
- Token scope is validated on every request; over-privileged tokens are rejected.
- Token issuance is audited and appears in the per-tenant audit log.
Rate limits
Public endpoints are rate-limited per source IP and per tenant hostname to protect against abuse:
| Endpoint | Limit |
|---|---|
POST /public/v1/privacy/dsar/submit | Implementation-defined per tenant; defaults protect against form spam |
GET /public/v1/privacy/notice | High throughput allowed; CDN caching reduces backend hits |
Rate limit headers follow the draft IETF RateLimit-* convention when limits are active.
Versioning
The public API follows a URL-versioned convention (/public/v1/). Breaking changes will increment the version. Non-breaking additions (new fields in JSON responses, new optional query parameters) are made without a version bump.
Transport security
All endpoints require HTTPS. Helix enforces Strict-Transport-Security: max-age=31536000; includeSubDomains on all responses. Plain HTTP requests to the public API are redirected (301) to HTTPS.
SDKs and client libraries
First-party SDKs are planned for TypeScript/Node.js and Python. Until then, use the REST API directly. See Public Endpoints Reference for curl examples.