API documentation

A map of the Heimdall API’s own documentation site: what each section covers and where to find it, from the endpoint reference to the data-protection documents.

The Heimdall API documents itself on its own site, artur-rios.github.io/heimdall-api. This site does not copy that material, because the API’s internals change with the API and the API’s site is rebuilt with it. This page is the map: every section of the API site, what it covers, and a link to it.

The API site’s top navigation has five entries: Documentation, Requirements, API Explorer, Test Coverage and GitHub. The Requirements entry opens the specification index. Test Coverage opens a coverage report that CI generates and does not commit.

Understanding and running the API

Section	What it covers
Home	The API’s landing page, with an entry point for each of its themes.
Documentation	Everything needed to understand, run, test and extend the Heimdall API.
Overview	The domain vocabulary (scopes, persons, roles, applications, permissions) and the rules that bind them.
Getting started	Prerequisites, configuration, migrations and running the API locally.
Architecture	The four layers, the CQRS mediator, the auditing decorator and the HTTP request pipeline.
Domain model	The entities, their relationships and the deletion cascade rules, as class diagrams.
Operations	Migrations, start-up guards, health checks, metrics, logging, rate limiting, data retention and the integrations.
Environments and deployment	The four environments and what each PostgreSQL has to allow.

Endpoints and the OpenAPI document

Section	What it covers
API reference	Every endpoint, the role that may call it, and the use case it implements.
API Explorer	Swagger UI over the published OpenAPI document. It is read-only: it shows each operation’s request and response shapes but does not send requests.
OpenAPI document	The OpenAPI document itself, as raw JSON.

The API has 61 operations, counted from its controllers; the committed OpenAPI document has the same 61. They fall into seven groups.

The reference page is not complete

At API 1.4.0 the API reference page does not list every operation. It omits POST /api/auth/register, PUT /api/scopes/{id}/self-registration, PUT /api/scopes/{id}/email-links, POST /api/auth/2fa/challenge/resend and POST /api/auth/erasure-reconciliation. The OpenAPI document and the API Explorer, which is built on it, have all 61.

Group	Route	Operations
Authentication	`api/auth`	21
Scopes	`api/scopes`	9
Persons	`api/persons`, `api/scopes/{scopeId}/persons`, `api/scopes/{scopeId}/owners` and related routes	13
Applications	`api/scopes/{scopeId}/applications`	6
Scope permissions	`api/scopes/{scopeId}/permissions`	6
Google users	`api/scopes/{scopeId}/google-users`	4
Health	`api/healthcheck`	2

Flows

The flows are sequence diagrams of the paths worth tracing end to end. The Flows index lists them all.

Flow	What it covers
Login	UC-11: password authentication, the uniform rejection and the branch into a two-factor challenge.
Two-factor authentication	UC-36 to UC-40: setup, confirmation, the challenge-token round trip and recovery codes.
Google sign-in	UC-24 to UC-29: enabling it per scope, sign-up and sign-in, and administering Google users.
Person onboarding	UC-06, UC-14 and UC-15: creating a person, the verification email and replacing a lost link.
Password recovery	UC-12 and UC-13: an endpoint designed around what it must not reveal.
Scope permission claims	UC-31 to UC-35 and FR-AU-08: how a scope permission ends up inside a JWT.
Audit logging	NFR-09: one decorator, every write, no handler changes.

Specification

The Requirements index lists the specification documents. The same documents, with a one-line summary each, are also on the Repositories page, linked to GitHub. The API site publishes them in two groups.

Product and engineering documents

Document	What it covers
Vision Document	Why Heimdall exists, who it serves, the stakeholders, the goals and what success means.
System Requirements Document	The functional and non-functional requirements, the data model, the endpoints, the authorization matrix and the deletion strategy.
Use Case Specification Document	The actor-facing use cases, with main flows and numbered alternative flows.
Technology Stack Document	The technologies, the libraries and their pinned versions.
Testing Specification Document	The unit and functional standards and the required coverage per use case.
Development Workflow Document	A use case from backlog to merged: branch, issue status, testing gate and pull request.
Operations & Infrastructure Document	Hosting, the four environments, the technical foundation and the health-check feature.

Data-protection documents

Heimdall processes personal data, so its specification includes the documents that the LGPD and the GDPR call for.

Document	What it covers
Data Protection Document	Who controls what, on what basis, shared with whom and across which borders: the record of processing under LGPD Art. 37 and GDPR Art. 30.
Data Protection Impact Assessment	The risks to data subjects and their mitigations, under GDPR Art. 35 and LGPD Art. 38.
Data Retention Schedule Document	How long each category of personal data is kept, why, and which periods the API enforces.
Privacy Notice	What Heimdall does with personal data, under LGPD Art. 9 and GDPR Art. 13 and 14.
Data Processing Agreement	The terms for processing a tenant’s users’ data, under LGPD Art. 39 and GDPR Art. 28.
Incident Response Document	What counts as a personal data breach, who declares one, the clocks that start and who has to be told.
Threat Model Document	The threats by trust boundary, and the residual risk.

Changes and contributing

Section	What it covers
Changelog	The notable changes in each release, rendered from the repository’s `CHANGELOG.md`.
Contributing	Build, tests and coverage, migrations, the OpenAPI document, branching and releasing, rendered from `CONTRIBUTING.md`.
Test coverage report	The ReportGenerator coverage report, generated in CI.

Where this site and the API site differ

This site explains Heimdall as a whole, and covers the UI as well as the API. The API site is the authority on the API: when the two disagree about an endpoint, a flow or a requirement, the API site, and ultimately the API’s source, is right.