Compass — Authentication Flow Engine

Compass is FerrisKey’s authentication flow engine. It records every authentication attempt as a structured flow — a sequence of named steps with individual outcomes, timings, and error details. Compass gives you deep observability into how users authenticate, where failures occur, and how long each step takes.

Why Compass?

Authentication looks simple from the outside: the user logs in and gets a token. But inside, a single login request can involve redirect validation, credential hashing, MFA challenges, external IdP callbacks, session creation, and token signing. When something fails, you need to know which step broke and why.

Without Compass, a failed login is just a 401. With Compass, you see:

How It Works

When Compass is enabled, every authentication request creates a CompassFlow. As the request progresses through credential validation, MFA challenges, token exchange, and finalization, each step is recorded as a CompassFlowStep with its own status and duration.

graph TD
    A[Flow Started] --> B[Authorize]
    B --> C[Credential Validation]
    C --> D{MFA Required?}
    D -->|Yes| E[MFA Challenge]
    D -->|No| F[Token Exchange]
    E --> F
    F --> G[Finalize]
    G --> H[Flow Completed]

Flow Lifecycle

Each flow progresses through a clear lifecycle:

Flow Structure

A CompassFlow captures the full picture of an authentication attempt:

Flow Status Values

Flow Steps

Each step within a flow records:

Step Types

Step Status Values

Configuration

When disabled, authentication works exactly the same — the flow recording is simply skipped. No flows are created, no steps are recorded, and no database writes occur. Toggle this off for realms where you don’t need flow-level observability.