Auth & Accounts

• File: Features/Accounts/AccountController.cs, Services/Keycloak.cs, Services/EmailComposerService.cs

Overview

Authentication is handled by Keycloak (identity provider), with hvc-api minting its own session/login codes on top. Each tenant is its own Keycloak realm (multi-tenancy via subdomain → realm resolution). Users sign in by:

• SSO / QR code — the mobile/headset apps display a QR login code and poll; the web user approves the login.
• PIN — device PINs are stored per user; used for meeting join and quick unlock.
• Offline tokens — allow limited offline login.

Tokens use a dual-scheme JWT setup: Keycloak tokens (from the IdP) and Internal tokens (issued by this API, carrying permissions). A custom policy selector picks the scheme per request.

REST endpoints (api/account/...)

Endpoint	Purpose
POST /api/account/login	Standard login (LoginRequest → LoginResponse)
POST /api/account/extendLoginCode	Extend the validity of a login code
GET /api/account/qrCode	Generate a QR login code (GenerateQRCodeCommand)
POST /api/account/{userId}/logout	Log the user out
POST /api/account/resetPin	Reset a user's PIN (ResetPinCommand)
POST /api/account/offlineToken?purpose=...	Issue an offline token
POST /api/account/offlineLogin	Login with an offline token
POST /api/account/refresh	Refresh the session (LoginMeta)
POST /api/account/impersonate	Impersonate another user (support flows)
POST /api/account/org	Org details for a tenant/org

Permissions

• Permissions are resolved from the user's role via the Authorizer and surfaced in the me/me-style queries (Features/Security).
• hvc-admin-api maintains roles/permissions; the web admin UI lets tenant admins assign them (see Admin section and Web admin).

Sign-in flow (web)

1. Client resolves tenant realm from subdomain (multi-tenancy).
2. Keycloak login-required → authorize code → token.
3. Client calls GraphQL `me` + `tenantConfig` to load user + permissions.
4. Access token refreshed ~every 40 s; SignalR uses it for the hub connection.

Related

• Keycloak service — identity provider config.
• Tenants & Admin — realm/tenant provisioning and the migrate endpoint.