API Overview

Base paths

The RealmSSO server (Fastify) exposes each module under its own versioned prefix, mounted in src/app.ts. There is no single catch-all API prefix — clients target the module path directly:

Liveness and readiness checks are mounted at the server root — GET /health and GET /readyz — not under /api/v1, since they exist for the load balancer and orchestrator, not API clients.

Authentication

Most of the API accepts one of two credential types, and which one a route accepts depends on the module. Connections, SSO Integration, Agent Clients, Webhooks, Observability and Audit accept either — though two routes are deliberately unauthenticated, because their caller has no credential to present: GET /api/v1/sso/resolve, which a login page calls before anyone has signed in, and GET /api/v1/connections/:id/initiate, the IdP-initiated sign-on URL an admin reaches from their identity provider's app tile. Observability accepts either on its four account-scoped reads, but not on GET /api/v1/observability/realm-co-residency, which is platform-operator authority and refuses a key whatever it holds. API Keys and Products accept only a vendor session, and minting a key is vendor-session only by design. Accounts accepts only a vendor session on every route but one — POST /api/v1/accounts, the bootstrap route, also accepts a platform-level key. Two modules use their own separate scheme instead: SCIM authenticates with a per-account bearer token (see SCIM API), and the Admin Portal accepts its own token via an X-Admin-Token header — then a short-lived session via X-Admin-Session or a cookie — rather than a vendor session or API key (see Magic Link Authentication).

• Vendor session (JWT). Issued by /api/v1/auth and verified by @fastify/jwt, either as a Bearer header or the realmsso_token cookie. Tokens expire after 24 hours. This is what the vendor dashboard uses on behalf of a logged-in user.
• API key. Sent as an X-API-Key header — never as a Bearer token. The server hashes the key with SHA-256 and looks up the ApiKey row by that hash — the raw key is never stored and is only ever returned once, in the create response. A missing header is MISSING_API_KEY; a key that is disabled, expired, or simply not found is INVALID_API_KEY. Both are 401.

Every API key carries a scopes array (e.g. connections:read, webhooks:write, or the wildcard *) recorded on the key. Every scope string is validated against an allow-list when the key is created. On every account-scoped route, authorization for the target account (requireOrgAccess) is checked as well.

That check is not the same for the two credentials. A vendor session must hold an AccountMembership row on the account and a role at least as high as the minimum the route names — viewer on every account-scoped GET, member on the mutating routes, and admin on setting an account's connection-error policy and on the whole API-key lifecycle — minting, re-scoping and revoking. An API key has no membership row and is not mapped onto a role: it is checked against the one account it was minted for, and then against its scopes. See Access Control for the tiers in full.

Request envelope & pagination

Single-resource responses are wrapped as { data: ... }. Paginated list endpoints add a meta block:

{
  "data": [ /* ... */ ],
  "meta": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

page and limit are optional query parameters, and limit is capped server-side regardless of what the caller requests: 100 on Accounts, Connections, and webhook deliveries; 200 on Audit and the observability event feed.

Error format

Every error on the /api/v1 surface — thrown application errors, Zod validation failures, Fastify-level parsing errors, and rate-limit rejections — is normalized by a single Fastify error handler into the same shape. SCIM is the exception: it answers in SCIM's own error envelope (see SCIM API).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [ { "path": "slug", "message": "Slug is used as a DNS label in this account's SSO hostname, and this one starts or ends with a hyphen, which no DNS label may do." } ]
  }
}

Rate limiting & CORS

@fastify/rate-limit caps every client to RATE_LIMIT_MAX requests (default 100) per RATE_LIMIT_WINDOW_MS (default 60 seconds), keyed on the request's resolved IP. The app trusts exactly one proxy hop — the ingress in front of the pod — as a predicate, trustProxy: (_address, hop) => hop === 0, so a client cannot spoof its own rate-limit bucket by setting X-Forwarded-For itself. Not trustProxy: 1: fastify 5.12.1 removed the numeric form from the type union and compiles a number to () => false at runtime (GHSA-3m5p-2c4r-xxw2), so the number fails closed and buckets every caller as the ingress address. Allowed browser origins are configured via the CORS_ORIGINS environment variable (comma-separated), and @fastify/helmet plus a small set of custom headers (X-Frame-Options, X-Content-Type-Options, HSTS) are applied to every response.

See Accounts API, Connections API, SCIM API, and Webhooks API for the endpoints themselves, or Accounts (Tenants) for the realm-per-account model those endpoints operate on.