Admin Account System

The Manage service implements a purpose-built administrator directory that is separate from customer identities. It stores control-plane operators, delegated tenant managers, and read-only auditors together with the access credentials required to call privileged APIs.

Account Personas and Records

Every administrator entry stores an immutable id, display name, granted role, and optional contact metadata. Platform operators run the Helium cloud and may assume any tenant context. Tenant administrators belong to a single customer tenant and can invite peers. Auditors observe configuration and compliance state without mutation rights. Each record retains lifecycle timestamps (creation, last login, invitation usage) so governance reports can be produced without touching runtime logs.

Registration Workflow

Administrator onboarding is handled by invitation and implemented inside AdminAuthService:

1. Invitation lookup – The service receives a RegisterAdmin command and uses FindAdminInvitationByToken to retrieve the invitation that seeded the registration. Missing invitations resolve to RegisterAdminResult::InvalidInvitation.
2. Usage guard – If the invitation was already consumed (invitation.used), the service short-circuits with RegisterAdminResult::InvitationUsed to stop replayed activation links.
3. Account creation – A new UUID is minted and passed to CreateAdminAccount together with the invite’s role and the operator-supplied profile fields. This persists the administrator row and binds it to the permission set determined during invitation issuance.
4. API key provisioning – generate_admin_token produces an opaque API key (passkey). The token plus key label (key_name) are stored through CreateAdminToken, ensuring future logins can authenticate against the database record.
5. Invitation finalization – UseAdminInvitation marks the invitation as used so the one-time link cannot be replayed.
6. Response – The service returns RegisterAdminResult::Success with the freshly created admin_id and the plaintext API token. The caller is responsible for presenting that key securely to the new administrator; it is never persisted in plaintext elsewhere.

This flow guarantees that registration can only occur with a valid invitation and that each administrator starts with at least one API credential for future logins.

Login Workflow

Subsequent logins exchange the stored API token for a short-lived JWT access credential:

1. API key lookup – AdminAuthService receives an AdminLogin command containing the submitted API token that was minted during registration (or from a later CreateAdminToken issuance). It invokes FindAdminPasskeyByToken to resolve the underlying admin key row stored in admin.admin_key. Absent or revoked tokens yield AdminLoginResult::KeyNotFound.
2. Account hydration – With the key resolved, the service loads the administrator profile through FindAdminById. Missing accounts are treated as a failed login to avoid leaking information about deleted users.
3. JWT configuration – The service clones its Redis connection and calls find_config_from_redis::<AdminJwtConfig> to load the current signing material, issuer, audience, and expiration settings.
4. Claim assembly – Using AdminJwtClaims, the service sets sub to the admin ID, name and role to the profile details, and timestamps (iat, exp) based on OffsetDateTime::now_utc() plus the configured TTL.
5. Token issuance – The encoded claims are signed using the JWT encoder from AdminJwtConfig::encode(). On success the service returns AdminLoginResult::Success(AdminAccessToken); failures bubble up as framework errors.

The caller receives only the access token string. Subsequent Manage API calls must include it (for example, as a Bearer token) so workers can authorize the request.

Access Token Semantics

The issued JWT embeds the administrator’s role in lower case (via role.to_jwt_string().to_lowercase()), the issuer/audience pair, and the expiry chosen by configuration. Manage workers validate tokens on every request using the same Redis-backed configuration, checking signature validity and time-based claims before resolving RBAC permissions. Because API tokens act as a second factor, operators are encouraged to rotate them regularly; new keys can be created through the same CreateAdminToken processor while old keys are revoked out-of-band.

Account Lifecycle

Beyond registration and login, Manage provides tools for invitation management, account suspension, and archival. Suspended accounts retain their historical record but cannot authenticate until reinstated. Archival removes active credentials yet preserves audit context, ensuring the administrator directory remains authoritative for compliance reporting.