Skip to content

API description (OpenAPI)

The console's own front end is the only supported client, but the HTTP API is described in OpenAPI 3 for reviews, audits and integration tests.

Where

GET /openapi/v1.json on the console URL (e.g. https://steward.client-example.ch/openapi/v1.json).

Environment Who can read it
Development Anyone (local development only)
Any other (Production, Staging...) A signed-in operator whose roles grant settings.manage. Anonymous: 401. Signed in without the permission: 403.

The document is never anonymous in production. To fetch it, sign in to the console in a browser with an administrator account and open the URL in the same browser (the session cookie is sent automatically), or reuse that session with your tool of choice.

What it contains

  • Every /api/ endpoint with a summary, grouped by tag (auth, users, groups, admin, ...). Helpdesk and onboarding endpoints appear only when the helpdesk is enabled (they are not mapped otherwise).
  • The status codes common to every endpoint: 400 (validation or missing antiforgery token) on state-changing calls, 401/403 on authenticated endpoints, 404 on routes with an id, 429 (rate limit) and 500.
  • The error body ApiError: { "code": "<stable_code>", ... }. The code is stable and translated by the front end (errors.* keys in web/src/locales/<language>/); some codes add details (field errors, conflicting values). Internal errors carry only a correlationId to search in the logs, never exception text.

Calling the API

  • Authentication is a server-side cookie session (__Host-steward), created by POST /api/auth/login (Active Directory) or by Teleport. There are no API tokens for this API. The one exception is the read-only fleet status for the MSP control plane (GET /api/fleet/v1/status, bearer token only): see Fleet API.
  • Every state-changing call (POST, PUT, DELETE) must send the X-CSRF-TOKEN header obtained from GET /api/auth/antiforgery in the same session.

For developers: summaries live in src/Steward.Api/Hosting/OpenApiDocumentation.cs. A test fails when a mapped endpoint has no summary, so add one there with every new endpoint.