Documentation on Heimdall API

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Heimdall is a centralized identity management API. Several client systems delegate their identity concerns to one deployment of it, and each of those systems gets an isolated slice of the data called a scope.

Everything else in the model is defined relative to that boundary.

The vocabulary

Term	What it is
Scope	A logical tenant boundary that groups the owners, users, applications, Google Users, and permissions belonging to one client system.
Person	A registered human identity — name, email, password hash, role, deletion status. A person has no scope column; its relationship to scopes is derived from its role.
Role	One of `SystemAdmin`, `ScopeAdmin`, `User`. A closed set of three rows.
Scope Owner	A person with the `ScopeAdmin` role — or a `SystemAdmin` who chose to — who owns a scope. Many-to-many: a scope has one or more owners, an admin may own several scopes.
Scope User	A person with the `User` role who belongs to exactly one scope.
Application	A registered non-human identity (another system), in exactly one scope, owned by exactly one Scope Admin who owns that scope.
Google User	An identity authenticated by Google rather than a password. Always `User`-equivalent, always in exactly one scope, stored in its own table with a direct `ScopeId`.
Scope Permission	A permission defined inside a scope. When `IncludeAsJwtClaim` is set, its name is added as a claim on JWTs issued for that scope.
Two-Factor Auth	An opt-in second step for a person — authenticator app, email, or both — backed by ten single-use recovery codes. Not available to Google Users.
Logical deletion	Setting `IsDeleted = true`; the row stays.
Hard deletion	Removing the row, with defined cascades.

How a person relates to a scope

This is the single rule that most often surprises newcomers: Person has no ScopeId.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

.NET 10 SDK
PostgreSQL — the API’s relational database.
Python 3 — only to run the migration menu script.
The pinned EF Core CLI tool. Restore it once after cloning:

dotnet tool restore

Building from source, running the test suites and the other contributor tooling are covered in Contributing .

Clone

The documentation site’s theme is a git submodule, so clone with submodules (or initialise them afterwards):

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Heimdall is a layered (DDD-flavoured) solution with CQRS in the application layer. Reads and writes travel different objects, through different mediators, into different handlers.

The layers

graph TB
 subgraph P["Presentation — ArturRios.Heimdall.WebApi"]
 CTRL[Controllers]
 SEC[Security: token issuers, mappers, filters]
 MAIL[Email senders]
 end
 subgraph A["Application"]
 subgraph CMD["ArturRios.Heimdall.Command"]
 CH[Command handlers]
 CV[FluentValidation validators]
 CS[Services: token, 2FA, email verification]
 AUD[Auditing decorator]
 end
 subgraph QRY["ArturRios.Heimdall.Query"]
 QH[Query handlers]
 HC[Health checks]
 end
 subgraph SHR["ArturRios.Heimdall.Shared"]
 MSG[Messages + status-code maps]
 OWN[IScopeOwnershipChecker, IActorAccessor]
 end
 end
 subgraph D["Domain — ArturRios.Heimdall.Domain"]
 ENT[Entities + Roles enum]
 end
 subgraph I["Infrastructure — ArturRios.Heimdall.Data"]
 CTX[AppDbContext]
 MAPS[Entity maps]
 MIG[Migrations]
 SEED[DatabaseSeeder]
 end

 CTRL --> CMD & QRY
 CTRL --> MSG
 CMD & QRY --> SHR
 CMD & QRY --> ENT
 CMD & QRY -->|repository interfaces| I
 I --> ENT
 SEC -.implements.-> CS
 MAIL -.implements.-> CS

The arrows only ever point inwards or sideways: Domain depends on nothing, and Application depends on Infrastructure only through repository interfaces (IAsyncRepository<T, long>, IAsyncReadOnlyRepository<T, long>) that Infrastructure implements. Presentation supplies the concrete adapters for the abstractions the Application layer declares — IAuthTokenIssuer, IEmailVerificationSender, IGoogleIdTokenVerifier — which is why swapping Mailgun for logging, or the real Google verifier for the refusing one, is a start-up registration decision and nothing else.

Domain model

Mon, 01 Jan 0001 00:00:00 +0000

The domain layer is intentionally anemic: entities are data holders with properties and navigation collections. Decisions live in the command and query handlers, so the diagrams below are a map of shape and relationship, not of behaviour.

The core model

The entities every request touches: a scope, the persons related to it through the two join tables, the applications and Google Users it contains, and the permissions it defines.

API reference

Mon, 01 Jan 0001 00:00:00 +0000

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.

API explorer

Mon, 01 Jan 0001 00:00:00 +0000

Every endpoint the API exposes, rendered from the published OpenAPI document . The document is generated from the controllers themselves — the summaries below are the ones in the source — and regenerated with python scripts/openapi.py. It is byte-for-byte what a running instance serves at /swagger/v1/swagger.json: both come from the same SwaggerConfiguration.

This explorer does not call anything

The page has no server behind it, so Try it out and Authorize are both gone — a token entered here could only be attached to a request, and no request can be sent. The padlocks stay, because which endpoints need one is worth knowing. To call the endpoints, run the API and use its own Swagger UI at /swagger — same document, with Authorize and Try it out working — or the .http files or Bruno collection in api-client/. For what each endpoint means and who may call it in prose, see the API reference .

Environments and deployment

Mon, 01 Jan 0001 00:00:00 +0000

The API runs in four environments. All of them use the same image and the same docker-compose.yml ; what differs between them is the env file, who deploys it and, mostly, what the host’s PostgreSQL has to be told to allow.

Environment	Where	Deployed by	`ASPNETCORE_ENVIRONMENT`	API at	Database
`local`	The developer’s Windows machine, Docker Desktop	By hand, `docker compose --env-file docker/local.env up -d --build`	`Development`	`http://localhost:8080`	`heimdall_local`, PostgreSQL on Windows
`development`	The VPS, on demand	Jenkins, on every push to `develop`	`Development`	`https://heimdall-api-dev.example.com`	`heimdall_development`, PostgreSQL on the VPS
`homologation`	The VPS, on demand	Jenkins, on every push of a `release/x.y.z` branch	`Staging`	`https://heimdall-api-hml.example.com`	`heimdall_homologation`, PostgreSQL on the VPS
`production`	The VPS, always on	Jenkins, on a green `release/x.y.z → main` pull request — it then merges and tags	`Production`	`https://heimdall-api.example.com`	`heimdall`, PostgreSQL on the VPS

example.com stands for the real domain throughout this page. In every VPS environment the API is also served under the web UI’s own host at /api/ (https://heimdall-dev.example.com/api/…, -hml, and https://heimdall.example.com/api/…), which is how heimdall-ui’s browser build calls it without CORS.

Operations

Mon, 01 Jan 0001 00:00:00 +0000

Migrations

The schema is managed with EF Core migrations, applied explicitly:

python scripts/migrations.py

The script asks which environment file to load (for the connection string), then offers list, create (generate), and apply. It needs dotnet tool restore to have been run once, for the pinned EF Core CLI tool. Authoring a migration is covered in Contributing .

The API never migrates on startup, and refuses to start when migrations are pending. The seeder checks GetPendingMigrationsAsync first and throws with the missing migration names: