Skip to main content
Version: 0.1.0-draft

Strataplane API

Management API, Telegraf and Vector agent APIs, Fleet emulation and the strataplane-agent API.

Generated from the server's handlers and types (UPDATE_OPENAPI=1 cargo test -p sp-api --features testing --test openapi).

  • Management endpoints live under /api/v1 on the management listener (UI, stratactl, CI, assistant): session cookie + CSRF header, or Authorization: Bearer spk_….
  • Tenancy (architecture.md §12): one host serves every tenant. A management request acts in the tenant of its credential: a token belongs to one tenant, a session is bound to the tenant chosen at login (POST /api/v1/auth/session). Every path below except /api/v1/auth/*, /api/v1/me and /api/v1/platform/* is tenant-scoped; a session bound to no tenant gets 403 auth.no_tenant there. /api/v1/platform/* takes a platform session or a platform token; in a self-hosted installation also a platform admin's credential of its tenant. Agent requests find their tenant through their credential, on one agent host for all tenants.
  • Service mode (architecture.md §12): the billing service pushes memberships and entitlements to /internal/billing/* with a Zitadel JWT of its provisioning machine user (billingJwt). A tenant without an active entitlement is read-only: every unsafe management request except POST /api/v1/billing/handoff and /api/v1/billing/revocations gets 403 tenant.read_only, and enrollments of new agents get the same.
  • Telegraf agent endpoints live under /agent/v1/telegraf on the agent listener, Vector agent endpoints under /agent/v1/vector.
  • strataplane-agent (journey runner) endpoints live under /agent/v1/helper on the agent listener.
  • Fleet emulation endpoints (/api/status, /api/fleet/...) live at the root of the agent listener because Elastic Agent hard-codes these paths.
  • Agents enroll with an enrollment token (spn_…), then authenticate with a per-agent credential (spt_… Telegraf, spe_… Fleet access API key, spv_… Vector, sph_… strataplane-agent), optionally over mTLS. Telegraf in class mode uses its class enrollment token throughout.

Conventions:

  • JSON bodies, UTF-8, parsed with the spec's limits on size, depth and key count. Exceptions: agent configs (application/toml), evidence downloads, the runner's multipart result upload; the LLM proxy request has no key count limit (a conversation grows with every turn). Spec file content travels as canonical TOML text in content.
  • Ids are UUIDv7; spec revisions are integers (r812); change sets and rollouts also have a number (CS-418, RO-17); hashes are lowercase hex.
  • Times are RFC 3339; durations, here and in the spec, are Go-style strings plus the unit d for days ("1h30m", "90d").
  • Pagination: ?limit= (default 100, max 1000) and ?cursor=, responses { "items": [...], "next_cursor": … }. Lists bounded by configuration (e.g. tokens, zones, pins, secrets, sinks) return { "items": [...] } unpaginated. Hosts and agents filter with ?selector= in the short selector form and sort with ?sort=: <field> ascending or -<field> descending, nulls last in both directions, ties by id ascending. Their cursor is opaque and holds the sort, the last row's sort value and id; a cursor of another sort is 400 invalid_cursor, an unknown field 400 invalid_query.
  • Mutable resources return ETag; writes accept If-Match (412 on mismatch). Change set file writes use the per-file base_hash instead.
  • Creating POSTs declare Idempotency-Key (kept 24 h per principal and tenant): a repeat is authenticated and authorized like a new request and returns the first successful response with its Location and ETag; a concurrent repeat waits for the first; a repeat with a different request gets 422. Requests that return a credential (API and enrollment tokens) take no key.
  • Mutually exclusive request fields are oneOf alternatives.
  • A request of the browser assistant names its chat in X-Assistant-Chat: <chat id> (assistant.md §1): its audit events have the actor kind assistant, the chat as actor and the user in on_behalf_of; authorization stays the user's. A header naming no chat of the caller is 400 assistant.invalid_chat.
  • Every response carries X-Request-Id: the request's own when it is at most 128 characters of letters, digits and -_.:/+=, else a new UUID.
  • Errors are RFC 9457 problem details plus code, diagnostics[] and the request_id. 400 (a malformed body or query: invalid_body, invalid_request, invalid_query, invalid_cursor), 401, 403, 404, 412, 413 (too_large: a JSON body over 8 MiB) and 429 can come from any management endpoint; operations declare them only where they mean something specific. A name, slug or other key that is taken is 409 <object>.exists (team.exists, host.exists, …); a write that lost a race for a revision or counter is 409 conflict.concurrent and can be retried.
  • Authorization follows architecture.md §7 and authorization.md; each management operation names its check in x-strataplane-authz (public, own, own_or, action, filter over the authorized resources, compound, platform) with the catalog actions. Lists, counts and groups include only authorized resources; filtering precedes pagination. A hidden resource is 404; a visible resource with a denied action is 403 (authz.denied). An authorization evaluation failure is 500 (authz.evaluation_failed), with no protected response data or mutation; policy/entity diagnostics remain server-side. Authentication failures remain 401. Permission decisions do not bypass domain validation, approval requirements or concurrency checks.
  • Grouping parameters are group_by, a comma-separated list of keys.
  • Actors (users and service accounts) appear as ActorRef (id, kind, display_name) wherever a field names who did something.
  • Long operations return 202 with an Operation to poll.
  • GET /api/v1/events is an SSE stream of change notifications; clients re-fetch what they display.
  • No endpoint returns a secret value; rendered configs show <secret:name@vN>.

Authentication​

Per-agent Telegraf token (spt_…), sent by Telegraf from TELEGRAF_CONTROLLER_TOKEN.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer