Build against the governed hosted surface: authenticated REST reads, a capability-gated operation channel, streamed import, a bearer-mode JavaScript client, signed webhooks, and first-party custom visuals.
Roux supports three implemented ordinary-authentication profiles. OIDC is a reserved provider name but is not currently an implemented direct provider.
| Provider | Credential | Contract |
|---|---|---|
| Native | Opaque server-side session in a Secure, HttpOnly, SameSite=Lax cookie | Every authenticated native-session POST /call and upload request requires the session-bound CSRF value in x-roux-csrf, including read operations sent through /call; the public health operation is the exception. Login, logout, activation, and password lifecycle stay server-managed. |
| External bearer | Authorization: Bearer <jwt> or the compatibility header x-roux-session: <jwt> | The configured IdP issues ordinary user tokens. Roux always verifies signature, allowed algorithm, and expiry; issuer and audience are verified when configured and are mandatory in the public-key/JWKS and multi-tenant topologies that require them. When its user directory is enabled, Roux also verifies admission and current authorization-store status. |
| Development bearer | Locally issued development token | Loopback-only and refused when network-exposed. Never use it as a production login. |
embed:true is refused./readyz/core is an internal subrequest only and the backend aliases /health, /livez, and /ready return 404 externally.ROUX_DEV_LOGIN is enabled with a symmetric secret and no real IdP/public key/JWKS; otherwise the route is absent. It accepts a development subject, optional topology-valid organization, bounded memberships, and attributes, then returns an ordinary token only after the same admission path accepts it. It never mints embed credentials.Success uses { ok:true, data }. Authentication, workspace resolution, authorization, row policy, and column policy are applied server-side where relevant. Workspace owners retain full-row access.
x-roux-workspace takes precedence over ?ws=, and neither value is proof of access. In ordinary workspace mode, a missing, unknown, or non-member selector resolves to the caller's isolated personal workspace; constrained profiles may impose a fixed target. Clients should verify the returned session/workspace projection before a consequential action.| Route | Result and availability |
|---|---|
GET /api/v1/state?ws=<workspace> | Returns data.state, the authorized workspace specification, when workspace-mode transport exposes getState. |
GET /api/v1/rows/<id>?ws=<workspace> | Returns data.rows and data.version for an authorized in-memory dataset slice. |
getRows. Use op:"page" for bounded row windows (up to the server limit) and op:"query" for server-side aggregation.curl -s https://your-roux-host/api/v1/state?ws=sales \
-H "Authorization: Bearer $TOKEN"POST /call accepts { op, args }. health is the only unauthenticated operation; every other network operation requires the configured credential. Every authenticated native-session call also requires x-roux-csrf, even when the selected operation is read-only. A successful operation returns HTTP 200 with { ok:true, value }. A typed engine failure preserves { ok:false, error } and uses its typed HTTP status. Desktop-only, secret, unknown, or unauthorized operations are refused before execution.
curl -s https://your-roux-host/call \
-H "Authorization: Bearer $TOKEN" \
-H "x-roux-workspace: sales" \
-H "content-type: application/json" \
-d '{"op":"query","args":{"entityId":"d1","dims":["region"],"metrics":[{"name":"total","expr":"SUM([v])"}]}}'Errors can include message, code, status, reason, retryable, storage-state, conflict, or current-version markers. Clients must handle at least 400, 401, 403, 404, 405, 408, 409, 413, 415, 422, 429, 500, and 503 and must not fall back to ungoverned data.
POST /api/v1/upload is a governed write route available only when workspace-mode upload authorization is wired. The optional x-roux-filename supplies the safe display name and format extension; omission defaults to upload.csv. The body is the CSV, TSV, or Parquet bytes. Roux authenticates and authorizes before reading body bytes, applies declared and measured size limits, streams with backpressure to a private temporary file, and then hands the server-owned path to DuckDB ingestion.
Operators configure byte ceiling, temp directory, free-space reserve, per-user/global concurrency, and body-idle timeout. The constrained public-demo profile denies this route.
/roux-sdk.js is a framework-free bearer-mode client. It provides getState, getRows, query, and low-level call, and throws a real RouxError for non-success responses or error envelopes.
<script src="https://your-roux-host/roux-sdk.js"></script>
<script>
const roux = RouxAPI.client({
base: "https://your-roux-host",
token: TOKEN,
workspace: "sales"
});
const state = await roux.getState();
const result = await roux.query({
entityId: "d1",
dims: ["region"],
metrics: [{ name: "total", expr: "SUM([v])" }]
});
</script>EXTERNAL_PUBLISH_NOT_PERMITTED. A server whose operator turned publishing off answers 503.Operator-configured subscriptions can receive a best-effort dataset.changed event after a successful operation classified as a governed write. The payload identifies what changed but contains no row data. Roux adds event, stable delivery-id, and timestamped HMAC-signature headers.
Delivery is fire-and-forget. There is no Roux-side durable queue or automatic retry. Verify the timestamp and HMAC against the raw body, reject replays, and use the delivery id as an idempotency key.
defineVisual() in src/visuals/registry.js registers a visual kind with defaults and a React render function; namespaced identifiers are a recommended convention, not a runtime-enforced rule. Registered visuals use the ordinary canvas geometry, selection, resize, rotation, and inspection seams. Custom visual code runs with first-party application trust; do not load untrusted author code without a separate sandbox.
ROUX_AUTH_PROVIDER selects the profile. External bearer deployments configure an allowed algorithm, verification key/JWKS, origins, and allowed hosts; issuer and audience are topology-dependent, with startup enforcing them where required. Native mode requires the user store, invite-only identity, and either in-process HTTPS or an explicitly trusted TLS proxy; its ordinary sessions do not require a JWT verifier. Any provider profile that will mint Roux-derived embed or publication credentials also needs the symmetric Roux session secret.
Webhook subscriptions and private-target policy, frame-ancestor origins, rate limits, upload storage/limits, audit paths, DuckDB limits, and readiness contracts are operator-owned configuration. The server refuses dangerous or internally inconsistent values rather than guessing.