AI API Mapper
Technical walkthrough →
Technical walkthrough →
/ docs · functional specification

The full platform
functional reference.

Every functional area of AI API Mapper documented at implementation depth so architects, security reviewers, and platform engineers can evaluate the product with real technical context.

Portal · Authentication & accounts
On this page

Portal Authentication And Account Management

Purpose

This functional area manages how human users access the Portal and maintain their own account security.

It covers both local platform authentication and federated sign-in through external identity providers such as Microsoft Entra ID and Keycloak.

Main Capabilities

  • username and password login
  • refresh-token based session continuation
  • logout
  • MFA setup, enablement, verification, and disablement
  • backup code generation and regeneration
  • tenant selection when users belong to multiple tenants
  • self-service account profile updates
  • self-service password change
  • password-change-required enforcement for local accounts
  • active session review and session revocation
  • light and dark display mode switching

Local Authentication

The Portal supports direct credential-based authentication for platform users.

Functionally this includes:

  • validating a user’s credentials
  • issuing authenticated portal sessions
  • guiding the user through tenant selection when multiple tenant assignments are valid
  • refreshing sessions without forcing repeated logins
  • terminating sessions on logout

This is the core sign-in path for platform-managed accounts.

Before validating credentials, the sign-in pipeline checks the user’s authentication mode. If the account is set to External only, local sign-in is blocked immediately and the user receives a clear error indicating that they must use their organisation’s identity provider. This check does not count towards brute-force lockout counters, because it is a configuration gate rather than a credential failure.

Repeated failed credential attempts for a local account result in a sign-in lockout. A locked-out account cannot authenticate until an administrator clears the lockout through the Users page. See Portal Tenant And User Administration for details.

For local sign-in, the platform can also require a password change before normal portal access continues. This typically happens when an administrator has set a new password for the user or when password rotation policy requires remediation. In that state, the user can authenticate but is restricted to the password-change flow until a compliant new password is chosen.

Bootstrap Administration

The platform includes a first-run bootstrap seeding mechanism that creates the initial super-admin account when none exists.

The bootstrap administrator password is not hardcoded in the platform. It must be supplied by the operator through environment configuration before the platform starts for the first time. If the password is absent or matches a known placeholder, the platform refuses to start in a production environment.

The bootstrap super-admin account is created with a mandatory password-change flag. The operator must choose a new, unique password on the first sign-in before accessing any other portal feature. This ensures that the initial credentials used during setup are never retained as a long-lived access path.

Multi-Factor Authentication

The Portal includes built-in MFA capabilities to strengthen operator sign-in.

Supported MFA functions include:

  • TOTP-based setup
  • verification during login
  • MFA enablement after setup
  • MFA disablement with verification
  • backup code issuance
  • backup code regeneration

This allows the platform to enforce stronger authentication for administrative users.

External Sign-In Through Identity Providers

The Portal supports federated sign-in through external identity providers using the OIDC Authorization Code + PKCE flow.

Supported external identity providers include:

  • Microsoft Entra ID
  • Keycloak

Functionally this includes:

  • login provider discovery
  • challenge creation for browser redirect flows
  • callback processing
  • tenant-aware provider resolution
  • tenant selection when users belong to multiple tenants
  • optional email-based account linking

This lets organizations integrate the Portal with enterprise identity infrastructure instead of relying only on local credentials.

During external sign-in, the pipeline checks the user's authentication mode after resolving the account. If the account is set to Local only, external sign-in is blocked and the user receives a meaningful message explaining that only local credentials are permitted for their account.

Account Self-Service

Authenticated users can manage their own account profile through the Portal.

Supported self-service actions include:

  • view current account details
  • update account profile fields
  • change password
  • review effective role assignments for the current session context
  • manage MFA state

Session Management

The Portal provides session visibility and session control.

Users can:

  • list their active sessions
  • revoke specific sessions

Super-admin users can also review and revoke sessions for other users when required by governance or security operations.

Revoking a session now takes effect immediately, everywhere. Previously a revoked session only stopped that session's refresh token from being renewed — an access token already in a client's hands kept working until it expired on its own, up to an hour later. A revoked session's access token is now rejected on its very next use, whether presented back to the Portal or to the Runtime, without waiting for it to expire naturally. This applies to every kind of session, including the RFC 8628 device flow and OAuth-client sessions described below. If the platform detects a stale or already-used refresh token being replayed — a signal that a token may have been stolen — it automatically revokes every other active session for that account with the same immediate effect, as a precaution.

Password changes and session revocations are also written into governance audit records as portal-auth configuration events so operators can trace administrative account security actions alongside normal sign-in activity.

Device Authorization Grant

The Portal supports the OAuth 2.0 Device Authorization Grant (RFC 8628), which lets AI agents and CLI tools authenticate without running a browser themselves.

This flow is used when an agent is running in an environment that cannot receive browser redirects, such as a terminal, a background service, or an automated pipeline.

Functionally the flow works as follows:

  • the agent calls the platform initiation endpoint and receives a short alphanumeric user code and a verification URL
  • the agent displays the code and URL to the operator and begins polling for a token
  • the operator opens the verification URL in a browser and is prompted to enter the code, or the code is passed automatically in the URL so the page pre-fills it
  • if the operator is not already signed into the Portal, they are redirected to the login page and then returned to the device page after authentication
  • the operator reviews the request and either approves or denies it
  • once the operator approves, the agent's next poll receives an access token and refresh token with the same permissions as the operator's portal session
  • if the operator denies the request, the agent receives an access denied response on the next poll

The platform enforces a minimum polling interval to prevent excessive load. If the agent polls too frequently it receives a slow_down response and should increase its wait before retrying.

Device flow sessions have a fixed expiry window. If the operator does not act before the session expires, the agent receives an expired_token response.

Device Verification Page

The Portal Web application hosts a dedicated verification page at /device. This page is intentionally accessible without authentication so that the operator can land on it directly from a browser without signing in first.

If the operator is not signed in when they reach the page, the page shows the session details and a sign-in prompt. After the operator authenticates, they are returned to the device page with the code pre-filled and can immediately review and act on the request.

If the operator arrives with the code pre-filled in the URL query string, the page performs an automatic lookup of the session without requiring a manual code entry.

The page presents the request in a clear approval or denial screen. The operator can approve or deny the request with a single action. After acting, the page confirms the outcome and instructs the operator that they can close the browser tab.

Audit Events

All device flow lifecycle events are written to the governance audit trail:

  • session initiated — records the initiating agent's IP address and session identifier
  • session approved — records the approving user, tenant scope, and session identifier
  • session denied — records the denying user and session identifier
  • token issued — records the user, tenant, and session identifier once the polling agent receives its token

Session identifiers correlate all events for a given device flow lifecycle across initiation, approval, and token issuance.

Session Expiry And Cleanup

Device flow sessions that remain in a Pending state beyond their expiry are automatically transitioned to Expired status by the Jobs Worker nightly data lifecycle job. Expired, denied, and approved sessions are purged from the database after the configured retention window.

Browser-Based Runtime Authorization

The Portal also participates in the OAuth 2.0 Authorization Code + PKCE flow used by browser-capable runtime clients.

Functionally, this flow now works as follows:

  • the runtime authorization endpoint validates the OAuth request and redirects the browser into the normal Portal login experience instead of rendering a separate minimal login form
  • the Portal preserves the OAuth authorization request across the full sign-in journey, including external identity provider redirects, MFA verification, and tenant or context selection when required
  • the login page shows a dedicated runtime-authorization review state so the operator understands that access is being granted to a client application through the current portal account
  • the review card presents a compact summary of the requesting application, including the callback host-derived application label and client ID when available
  • if the operator is already authenticated when the request arrives, the Portal does not complete the handoff automatically; it now requires an explicit confirmation click before runtime access is granted
  • once the operator confirms, the Portal completes the authorization handshake and redirects the browser back to the client callback URI with the issued authorization code

This closes the functional gap that previously affected accounts using MFA or external identity providers during runtime authorization.

Operational Importance

This area is important because it protects the administrative surface of the platform.

From a functional standpoint, it ensures that:

  • only valid users can access portal features
  • higher-risk access can be protected by MFA
  • users can maintain their own access hygiene
  • operations teams can respond to suspicious or unwanted sessions
  • each account's permitted sign-in methods are enforced consistently across both local and external authentication paths
PreviousOverviewPortalNextTenant & user adminPortal