Security

​

Where to find it

Settings > Security (/dashboard/settings/security). Your widget key (ab_live_...) is managed on Setup > Install, not here. This page is for account security and identity verification only.

​

Two-factor authentication

Halo supports TOTP-based 2FA (Authenticator app, 1Password, Authy, Google Authenticator, etc.) with single-use recovery codes for fallback.

​

Enabling 2FA on your own account

Open Settings > Security and click Enable 2FA:

1. Scan the QR code with your authenticator app (or copy the secret manually)
2. Enter the 6-digit code your app shows
3. Save the 10 recovery codes that are shown once and never shown again

The setup dialog won’t let you close it until you confirm you’ve saved your recovery codes.

​

Signing in with 2FA

After password (or Google) sign-in we route you to a challenge screen. Enter the 6-digit code from your authenticator app to finish signing in.

​

Lost your authenticator?

Click Use a recovery code on the challenge screen. Each recovery code works exactly once. Using a recovery code disables your current authenticator, and we send you straight to the security page to set up a new one. This matches the standard GitHub/Google flow and means a stolen device’s TOTP secret is invalidated as soon as the legitimate user signs in via recovery. You can regenerate a fresh batch of 10 codes at any time from the Recovery codes button. Generating new codes invalidates the old set.

​

Disabling 2FA

Click Disable under your 2FA status. We require an AAL2 session (i.e. you must have completed a TOTP challenge during this sign-in) so a stolen-password attacker can’t quietly turn 2FA off. Disabling deletes your factor and any remaining recovery codes.

​

Org-wide enforcement

Admins can flip Require 2FA for everyone. When on:

• Any teammate without 2FA is blocked from the dashboard until they enroll
• They land directly on the security page with the setup dialog open
• The MFA challenge is required on every fresh sign-in for already-enrolled teammates

Stored as two_factor_required: true on teams.settings.security. The middleware caches the flag for up to 5 minutes, so policy changes propagate within that window.

​

Session timeout

Set the session timeout (in minutes) for inactive teammates. After N minutes without activity, they’re logged out and must sign in again. Range: 5–1440 minutes. Saved on blur.

​

Identity verification

Use an identity secret (ha_secret_...) to sign JWTs that prove a visitor really is the user_id they claim. Without it, anyone who reads your public widget key from your site’s HTML can impersonate another user’s chat history and tickets. Configure identity verification on this page:

1. Generate identity secret (shown once; store it server-side only)
2. Choose a mode: Off, Monitor (recommended while integrating), or Enforce
3. Watch production health on this page while in monitor mode

See Identity Verification for JWT minting examples and SDK token refresh.

​

Verification modes

When you generate a secret, Halo starts in monitor mode so flipping verification on does not instantly 403 every logged-in visitor before your backend mints tokens.

​

Production health and enforce gate

Once your widget is deployed, this page tracks identity checks from real production traffic:

• Healthy — verified requests are succeeding. The banner shows the time of the last verified request.
• Warning / failing — missing, expired, or invalid tokens are reaching the API. The banner explains the most common cause (expired JWT, missing token, signature mismatch, etc.).

Enforce is gated. You cannot switch to enforce until:

1. At least one verified identity request landed in the last 24 hours, and
2. No identity failures were recorded in that same window.

This prevents the common failure mode where enforce is enabled before server-side JWT minting is wired up, which blocks chat history, tickets, and live agent polling for every logged-in user. While integrating, stay in monitor, confirm this page shows healthy checks, then switch to enforce.

​

Widget key vs identity secret

Copy and regenerate your widget key on Setup > Install.

​

What’s not here

A few things you might expect that aren’t on this page:

• Widget key — Setup > Install
• Server-only REST API keys — coming in a future release; this page will host them when available
• SSO / SAML — not exposed in this UI today
• Audit logs — view-only audit logs aren’t surfaced in the dashboard
• Active session list — not currently available

If you need any of these for compliance, contact your account manager.

​

Where to go next