Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
Console OverviewPlans and StorageOverview DashboardAuthentication FlowsConfigurationsTemplates and Policy WorkflowsEventsHistory and SessionsEscalationsAgentsConnectorsKnowledge BaseKnowledge LifecycleExportsCost and SpendWalletsMy UsageGateways and ActionsGateway KeysNotificationsWebhooksAudit LogVersioned RolloutMembers, Teams, and RolesSecurity SettingsBilling and PlansSettings and Gateway Config
API Reference
Gateway
Workflow Guides
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Policy Reference
FAQ

Authentication Flows

Keeptrusts supports multiple authentication flows for the console, chat workbench, and API.

Use this page when​

  • You need to understand how users sign in to the console, chat workbench, or API.
  • You are configuring SSO (SAML/OIDC) for your organization and need to understand the flow.
  • You are integrating the chat workbench and need to understand the PKCE-based auth handoff.
  • You are debugging a login failure and need to trace the authentication path.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Console login​

Email and password​

The standard login flow:

  1. Enter email and password on the login page
  2. If MFA is enabled, enter the verification code
  3. On success, a server-side session is established
  4. The browser never holds the upstream API bearer token

SSO (Single Sign-On)​

Organizations can configure SAML or OIDC SSO:

  1. Click Sign in with SSO on the login page
  2. Enter your organization identifier
  3. You are redirected to your identity provider
  4. After IdP authentication, you are redirected back to the console
  5. A server-side session is established

SSO configuration is managed in the security area of the console and exposed according to your deployment and plan.

Passkeys​

If passkeys are registered, they appear as a login option:

  1. Click Sign in with Passkey
  2. Authenticate with your hardware key or biometric
  3. Session is established

Registration​

New users register through:

  1. Invitation link — Sent by an organization admin via email
  2. Self-registration — If enabled for the organization

The registration flow includes:

  • Email verification
  • Password creation with strength requirements
  • Optional MFA enrollment
  • Approval or review if the organization requires signup approval

If approval or verification is still pending, the user may see a pending-activation state before they can reach the full workspace.

If an approved account is provisioned with a temporary password and the user signs in with email and password, Keeptrusts routes that first successful password sign-in to a dedicated Change Password screen before Overview or chat. The user must replace that temporary password, then sign in again with the permanent password.

Google, SSO, and other non-password sign-ins do not stop on that forced password screen.

Password recovery​

  1. Click Forgot Password on the login page
  2. Enter your email address
  3. Check email for the reset link
  4. Set a new password

First-run onboarding after sign-in​

What happens after sign-in depends on the product surface and the user's role:

  • Console users land in the authenticated console shell and confirm organization context.
  • Chat-first users can be returned to the chat workbench through a one-time auth handoff.
  • First org admins or sole active users land directly in the chat workspace when no deployment exists yet. The workspace stays available while the first provider deployment or gateway setup is completed.
  • Non-admin users without an eligible deployment can be shown a request-admin-setup flow instead.

See Onboarding Flows for the role-based paths.

Chat and tasks workspace entry​

The chat and tasks workbenches authenticate through the console using the same server-side session boundary as the rest of the console:

  1. A signed-out user opens /chat or /tasks.
  2. Keeptrusts redirects the browser to /login with a returnTo parameter for the requested workspace.
  3. The console authenticates the user and establishes the server-side session.
  4. After authentication, the browser is returned to the requested chat or tasks workspace.
  5. The browser never sees the upstream API bearer token.

If signup approval or verification is still pending, the user may return to a pending activation path instead of an immediately active workspace.

API authentication​

For programmatic access:

  • Bearer API keys — Long-lived tokens for automation
  • JWT sessions — Issued by POST /v1/auth/login
  • CLI login — kt auth login for interactive sessions

For AI systems​

  • Canonical terms: Keeptrusts authentication, console login, chat workspace entry, tasks workspace entry, SSO (SAML/OIDC), passkeys, MFA, bearer API keys, JWT sessions, server-side session.
  • Console surface: Login page, registration page, dedicated change-password page, password recovery, SSO redirect.
  • CLI command: kt auth login.
  • API endpoint: POST /v1/auth/login (issues JWT), POST /v1/auth/register.
  • Security boundary: The browser never holds the upstream API bearer token. Console, chat, and tasks use the same server-side BFF session boundary.
  • Related pages: Security Settings, Onboarding Flows, Customer Journeys.

For engineers​

  • Console session is server-side (iron-session with SameSite=Lax cookies). The browser only receives an authenticated flag, CSRF token, and expiry.
  • Workspace entry: Signed-out /chat and /tasks requests should redirect to /login with returnTo preserved. If login fails with a redirect loop, check cookie settings and SameSite policy.
  • SSO requires configuration in Settings → Security — you must provide the IdP metadata URL or manual SAML/OIDC configuration.
  • For programmatic access, use kt auth login (interactive) or create a bearer API key in Settings → Access Keys.
  • If registration returns pending_approval, the user is in a review queue — this is not an error state.
  • JWT tokens support key rotation via the kid header. Multiple verification keys can coexist during rotation.

For leaders​

  • SSO (SAML/OIDC) centralizes identity management with your existing IdP, reducing credential sprawl and enabling automated deprovisioning.
  • MFA and passkey support provide defense-in-depth for high-privilege accounts managing AI governance policies.
  • The server-side BFF model means a browser compromise cannot exfiltrate tokens that authorize AI requests — reducing blast radius.
  • Signup approval gating lets you control who joins the organization before they access any governed AI system.
  • Redirected workspace entry ensures users authenticate before opening chat or tasks without any elevation of privilege beyond their console session.

Next steps​