API overview

Address

Every route in these pages is a path on the API origin. Set the origin once in your shell. Then add the path.

API=https://api.realmsso.com
curl -H "X-API-Key: <your-api-key>" "$API/api/v1/connections?accountId=<account-id>"

The API has no interactive explorer in production.

Two checks sit at the root, outside /api. GET /health answers while the process runs. GET /readyz checks the database and the cache. It answers 503 when either fails. The status code of /readyz does not depend on the sign-in service. It is not a status page.

Route prefixes

The server registers the prefixes below. A prefix with no reference page says so in the last column. Some of those prefixes have a concept page: Admin Portal, Invite links and Monitoring and health.

Authentication

Most routes accept a dashboard session token or an API key. The table above names the credential for each prefix. These routes need no credential, because their caller has none:

• The sign-in routes under /api/v1/auth. GET /api/v1/auth/me is the exception.
• GET /api/v1/sso/resolve and GET /api/v1/connections/:id/initiate.
• The two SCIM discovery routes and the contact routes.
• GET /health and GET /readyz.

Dashboard session token

A dashboard user signs in with a sign-in link. The sign-in returns a session token and a refresh token. The session token is valid for 24 hours.

Send the session token as Authorization: Bearer <token>. A browser holds it in the realmsso_token cookie.

The refresh token is valid for 30 days. Send it to POST /api/v1/auth/refresh. The response holds a new session token and a new refresh token.

API key

An API key belongs to one account. Send it in the X-API-Key header. Never send it as a Bearer token. A key starts with ss_.

RealmSSO stores the SHA-256 hash of a key and its first 8 characters, never the whole key. The create response shows the key once. A new account key holds the scope * and has no expiry, unless you set otherwise.

A request that carries the X-API-Key header is checked as an API key. A request without it is checked as a dashboard session. With neither credential, the answer is 401 with the code UNAUTHORIZED. A key that is disabled, expired or unknown returns 401 with the code INVALID_API_KEY. Only a dashboard session can make, change or revoke an API key.

Other credentials

SCIM uses a bearer token for each account. See SCIM directory sync. The Admin Portal API takes the IT admin's invite-link token in the X-Admin-Token header. That token works once.

After it, the portal session works through the X-Admin-Session header or the realmsso_admin_session cookie. The whole portal session ends 30 minutes after RealmSSO made the invite link. See Invite links.

Roles on an account

A dashboard session holds one role for each account it belongs to. The roles rank viewer < member < admin. A role also holds every right of the roles below it. RealmSSO reads the role again on each request. It refuses a role that it does not know.

An API key has no role. RealmSSO checks that the key belongs to the account in the request. Then it checks the scopes of the key. No route adds a member, removes a member or changes a role. See Access control.

API key scopes

Scopes apply to API keys only. A dashboard session carries no scopes. The server accepts these scope names and no others.

Five scope names that earlier documentation listed no longer exist: accounts:read, accounts:write, scim:read, scim:write and admin-portal:generate. No route ever checked them. Naming one when you make or change a key returns 400.

On account routes, a 403 with the code FORBIDDEN has these causes:

• The dashboard user has no membership on the account.
• The role of the dashboard user is lower than the route needs.
• The API key belongs to another account, or to no account.
• The API key lacks a scope that the route needs.
• The route needs platform-operator authority and the caller lacks it. An API key never holds it.

A few routes use their own 403 code, for example CONNECTION_NOT_BROKERING.

Request and response shape

A single resource comes back as { "data": ... }. A paginated list adds a meta object.

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

page and limit are optional query parameters. The server caps limit whatever the caller asks. The cap is 100 for accounts, connections and webhook deliveries. The cap is 200 for the audit log and the observability event feed.

Errors

Every error on the /api/v1 routes has the same shape. This holds for application errors, validation failures and rate limit rejections. SCIM answers 401, 403 and 404 in its own format. See SCIM directory sync. A SCIM body that fails validation gets the standard format below.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [ { "path": "name", "message": "Required" } ]
  }
}

The server can refuse a request before any route runs. Malformed JSON and an unsupported media type are examples. The answer has a 4xx status. Its code is BAD_REQUEST or a more specific code.

Rate limit and response headers

RealmSSO limits each client address to 200 requests per window. We measured the limit on production on 2026-10-03: the x-ratelimit-limit response header showed 200. The window is 60 seconds in our deployment settings. We did not measure the window. A request over the limit gets 429 with the code RATE_LIMITED.

The API server counts requests in its own memory. The webhook test route and the contact routes have their own, lower limits.

Every API response carries security headers, including HSTS for one year. We captured the headers on production on 2026-10-03. A browser request from another origin works only for an origin that RealmSSO allows.

See Accounts API, Connections, Connection status, SCIM directory sync and Webhooks API for the routes. Accounts and isolation explains the realm that each account has.