CONTROL API · HTTP REFERENCE
Stable request contracts for authenticated control operations.
The API uses same-origin HTTPS, JSON objects, opaque server-side sessions, per-session CSRF tokens for mutation, explicit roles, and structured errors.
1. Request conventions
Requests use UTF-8 JSON objects and must declare Content-Type: application/json. Transfer-encoded request bodies are rejected. The API accepts only documented methods; unsupported methods return 405 with an Allow header.
| Header | Direction | Purpose |
|---|---|---|
| Content-Type | Request | Must be application/json for body-bearing routes |
| X-CSRF-Token | Request | Required for authenticated mutation |
| X-Request-ID | Response | Unique correlation identifier |
| Cache-Control | Response | no-store for API responses |
2. Authentication routes
- GET /api/auth/config
- Returns the public Turnstile site key, action, and enabled state without exposing the provider secret.
- POST /api/auth/login
- Requires a single-use
turnstile_token, validates hostname and action through Siteverify, then verifies credentials and either creates a session or returns a short-lived MFA challenge. - POST /api/auth/mfa
- Completes a valid challenge and issues the host-scoped session cookie.
- GET /api/auth/session
- Returns the resolved public user profile and current CSRF token.
- POST /api/auth/logout
- Revokes the server record and clears the browser cookie.
- POST /api/auth/recovery
- Creates a uniform, rate-controlled recovery case without confirming identity existence.
3. Resource routes
GET /api/v1/resources lists up to 250 control records and accepts an optional validated kind filter. POST /api/v1/resources creates one validated request for a data space, pipeline, transfer, or access review.
{ "kind": "pipeline", "data": { "name": "telemetry-compaction", "owner": "Edge Platform", "source": "us-east-4", "target": "eu-north-1" } }Creation returns 201, a generated resource ID, initial state, actor ID, and creation time. The API rejects identical source and target regions and applies conservative identifier and payload limits.
4. Actions, settings, and audit
POST /api/v1/actions records an authorized control action. GET and POST /api/v1/settings read and update the current user's notification preferences. GET /api/v1/audit is restricted to designated audit roles and returns the latest 100 events.
Disabled buttons improve clarity, but session, CSRF, role, input, and rate checks are repeated by the server.
5. Structured errors
{ "error": { "code": "csrf_validation_failed", "message": "The request could not be verified.", "request_id": "req_…" } }| Status | Class | Retry rule |
|---|---|---|
| 400 | Validation | Correct the request first |
| 401 | Authentication | Establish a new session |
| 403 | Authorization, origin, or browser challenge | Complete the required check or change authority |
| 409 | State conflict | Refresh and re-evaluate |
| 429 | Rate control | Wait before retrying |
| 503 | Verification dependency unavailable | Retry only after a fresh browser challenge |
6. Limits and compatibility
- JSON request body: maximum 64 KiB.
- Stored resource payload: maximum 16 KiB after compact encoding.
- Resource list: maximum 250 records per response.
- Audit list: maximum 100 recent events per response.
- Authentication, recovery, MFA, and control actions use separate attempt windows.
Clients should treat undocumented fields as non-contractual and must not infer authorization from a successful read response.