API reference

Schema-level documentation — every parameter, every request and response body — is published as an OpenAPI document and rendered by the API explorer , which is the same document a running instance serves through its own Swagger UI at /swagger. To call the endpoints, use that, or the .http files or Bruno collection in api-client/.

This page is the map — what exists, who may call it, and which use case it implements.

Reading the “Who” column

Two rules apply everywhere and are not repeated per row:

• The identifier in a path is always a PublicId (GUID), never an internal id.
• A challenge token (issued by a 2FA-gated login) is rejected by every endpoint below except POST /api/auth/2fa/verify, with a 401.

Authentication — /api/auth

Every anonymous endpoint here is rate-limited to 10 requests per minute per IP. Each of them checks a credential, and none is protected by a token — see Operations for why that matters and what the limit does not replace. The authenticated endpoints that check a password or a second factor — 2fa/enable, 2fa/confirm, 2fa/disable, 2fa/recovery-codes/regenerate, erasure-request and PUT /persons/{id} — share the same limit.

The 2FA endpoints never name a person: the subject is always the caller, read from the bearer token, so a caller can only ever act on their own configuration.

A token naming a restricted identity (UC-44), or one logically deleted and not yet anonymised, is refused everywhere with a 401 — except data-export, erasure-request, processing-restriction and processing-restriction/lift, through which the subject exercises their own rights (NFR-24). Those answer with the use case’s own flows instead: a restricted subject can export, request erasure — which lifts the restriction, so the erasure is not held behind it — lift their own restriction, and is told a second restriction is a conflict (AF-44a).

A restricted identity can still sign in — login, 2fa/verify and google answer 200 with processingRestricted: true and a subject-rights-only token (UC-11 AF-11i, UC-25 AF-25e). That token claims no scope and only those four endpoints accept it; every other endpoint answers 403, even after the restriction is lifted, when the subject signs in again for a full token.

Scopes — /api/scopes

Persons — /api

Applications — /api/scopes/{scopeId}/applications

An application’s owner must be a ScopeAdmin or SystemAdmin who owns that scope — a User may never own one (FR-AP-03).

Application credentials — /api/scopes/{scopeId}/applications/{id}/credentials

A Scope Admin may manage the credentials only of an application they own, in a scope they still own, the rule GET/PUT /{id} apply (FR-AP-12).

Application tokens — /api/applications

The Application authentication guide is the page for the service consuming these tokens.

Scope permissions — /api/scopes/{scopeId}/permissions

Owning the scope is the whole of the authorization to manage its permissions — a permission has no owner of its own. A permission with IncludeAsJwtClaim set has its name folded into the JWT of identities acting within that scope (FR-AU-08); see Scope permission claims .

Google Users — /api/scopes/{scopeId}/google-users

The by-id read carries no role attribute for a concrete reason: a Google User’s token is User-role, so any attribute strong enough to keep other Users out would lock out the actor UC-27 explicitly grants. The listing admits none of them.

Both deletions take the scope’s PublicId in the path and refuse a Google User reached through the wrong scope.

Audit trail — /api/audit-log

An entry is shown as stored: an actor the retention pass has cleared reads as null, so filtering by actorId cannot find it. action is the command’s type name, matched exactly (CreateScopeCommand). A Scope Admin is refused — the trail has no scope column to divide it by.

Health check — /api/healthcheck

The API also answers both at the root, /healthcheck and /healthcheck/detailed, for the container health check and yggdrasil’s status page, which call it on its own port. Behind Traefik, only the /api/ addresses reach it from the web UI’s host.

Response shape

Every endpoint answers one of two envelopes:

// DataOutput<T>
{
  "data": { /* the resource, or null */ },
  "messages": ["Scope created successfully"],
  "errors": [],
  "success": true
}

// PaginatedOutput<T> — every list endpoint
{
  "data": [ /* the page */ ],
  "pageNumber": 1,
  "pageSize": 20,
  "totalRecords": 137,
  "messages": [],
  "errors": [],
  "success": true
}

The HTTP status comes from the handler’s message, mapped through the area’s message map (a dictionary from message text to status code), rather than from the controller choosing a status per branch. Same message, same status, everywhere it is returned.

List endpoints accept pagination and filter parameters, all validated before the query runs (NFR-10), and most accept includeDeleted=true to see logically deleted rows.

Malformed requests

A request that cannot be bound — a body that is not JSON, or a value of the wrong type in the body or query string (?succeeded=maybe, {"name": 123}) — answers 400 with the error The request is malformed., on every endpoint (NFR-10). The answer is a DataOutput envelope even on list endpoints. Authentication and role checks come first, so a caller without a valid token still receives 401, and one of the wrong role 403; refusals that depend on data, made in a handler, come after the 400.

A query parameter that is not nullable no longer falls back to its default when it is empty or unparseable: ?pageNumber=, ?pageNumber=abc, ?pageSize=, ?includeDeleted= and ?includeDeleted=1 are all 400. A nullable one sent empty (?succeeded=) still binds to null and is ignored. A missing required field is not a binding failure: it keeps the field’s own message from the validator.

Of the endpoints that take a body, only POST …/credentials accepts an empty one, meaning “no expiry”.

Errors that are deliberately vague

Some responses tell the caller less than the API knows, on purpose:

• POST /api/auth/login answers the same “invalid credentials” error whether the email is unknown, the password wrong, the person logically deleted, or their scope gone (AF-11a…AF-11e). The checks still run in the specification’s order so the code reads against UC-11 — only the answer is uniform.
• POST /api/auth/password-recovery answers identically whether or not the address belongs to anyone — in the same time, too: it only queues the request, and the lookup, the token and the email happen after the response. A Mailgun failure is logged rather than surfaced — an email outage must not turn into a 500 that confirms an anonymous caller’s guess.
• POST /api/auth/google answers alike for an unverifiable token, a token that does not carry the nonce the request sent, and a Google User whose account is gone (AF-25a, AF-25g, AF-25d).
• POST /api/auth/password-reset and POST /api/auth/verify-email answer “Invalid token.” both for a token nobody issued and for one whose person has since been restricted, deleted or anonymised, or can no longer sign in (AF-13e, AF-14d).

The specification

§5 of the System Requirements Document lists the endpoints as specified, and §7 is the full authorization matrix — every action against every role, including Anonymous. The Use Case Specification Document gives each endpoint’s main flow and every numbered alternative flow.