Reference
SCA API
The SCA exposes two versioned API surfaces — a provider/staff control plane and a CSP tenant front door — documented in full in the OpenAPI reference at /api.
Overview
The Sendense Central Appliance (SCA) publishes its control plane and its tenant front door as a single OpenAPI 3.1 reference, served at /api. That reference is the authoritative, self-contained description of every route, request, and response on the appliance.
A liveness endpoint sits at the server root; every other route is under /api/v1. The surface is path-versioned, and changes within v1 are additive only — new routes and fields are introduced, and existing ones are never repurposed.
Generated from the shipped routes
The reference is generated directly from the appliance route table and drift-checked in CI, so it always tracks the shipped surface.
Two API Surfaces
The SCA presents two distinct API surfaces to two different kinds of caller:
- A provider control plane, in the staff realm, for MSP and CSP operators. It covers authentication, tenants and users, appliance enrollment and fleet health, alerts, billing and rate cards, licensing and license pools, storage and partner repositories, provisioning, and hosts and container sets.
- A tenant front door, in the tenant realm, for an end tenant. It covers tenant authentication, per-tenant feature entitlements, and an allowlisted read-and-write proxy into the tenant's own Sendense Hub Appliance (SHA).
- CSP-edition routes — including the tenant front door — return 403 when the SCA runs in the MSP edition.
Authentication Realms
Callers authenticate in one of two separate JWT realms. The realm a caller belongs to is fixed by where it logs in, and the two are cryptographically isolated:
Conventions
Every error response uses the same shape — a single human-readable message — paired with a conventional HTTP status code for the condition:
{
"error": "<human-readable message>"
}Login rate limiting
Tenant login and federated-callback routes are rate-limited per client IP and answer with 429 and a Retry-After hint when the limit is exceeded; reads are safe to retry with backoff.
Idempotency And Async
Delegated staff writes and zero-touch onboarding both run asynchronously, and their outcomes are learned about by polling:
- Delegated-operation writes are idempotent: an idempotency key that is unique per appliance makes a retried submission return the original operation rather than starting a second one.
- An operation moves through pending, dispatched, and running to a terminal succeeded or failed. A caller submits the write and then reads back the outcome by polling — there are no webhooks.
- The submit and poll routes are SCA routes. The SCA dispatches each write to companion endpoints on the tenant's own SHA, where the operation actually executes and where the grant is authorized — an API consumer never calls the SHA directly to submit or poll.
- Zero-touch onboarding is polled the same way: a run is started and then polled to a terminal complete or failed.
Full Reference
The complete API — every route, parameter, request body, and response, with examples — lives in the OpenAPI reference and is not duplicated here.
Read the full reference at /api
The self-contained OpenAPI reference is served at /api and is discoverable from the site navbar and footer. Treat it as the authoritative description of the surface.
Related Docs