Two-factor sign-in (authenticator app, security keys, passkeys)¶

Accounts that sign in to CertIntel with a password can add a second step:

• a 6-digit code from an authenticator app (TOTP, RFC 6238), such as Microsoft Authenticator, Google Authenticator, 1Password or Bitwarden;
• a security key such as a YubiKey, touched after the password;
• a passkey, saved on your computer, your phone or your password manager and unlocked with your fingerprint, face or PIN. A passkey can also sign you in on its own, without your password.

You can use any of them, or several. Each person sets it up for their own account; an administrator can make it required for the whole workspace. It is available on every plan.

Two-factor sign-in applies to local password accounts only:

Setting it up¶

Open the account menu and choose Account security (/account/security). The first second factor you add turns two-factor sign-in on, shows your recovery codes once, and signs you out of every other session; the session you used stays signed in. Save the codes, then choose I have saved them.

Authenticator app¶

1. Under Authenticator app, choose Set up an authenticator app.
2. Scan the QR code with your authenticator app. If you cannot scan it, copy the key under Can't scan it? Enter this key instead, or the Setup link (otpauth://); both have a Copy button.
3. Enter the 6-digit code the app shows and choose Turn on two-factor sign-in (Add the authenticator app when a security key or passkey already turned it on). Nothing changes until a correct code confirms the setup; Start again with a new key discards the unconfirmed key.

Security key or passkey¶

1. Under Security keys and passkeys, choose Passkey or Security key, give it a name if you like (for example "Work laptop" or "Blue YubiKey"), and enter your password.
2. Choose Add and follow your browser: touch the key, or confirm with your fingerprint, face or PIN.

The form appears only in a browser that supports security keys and passkeys (WebAuthn). Adding or removing a key always asks for your password. You can have up to 10 security keys and passkeys. Use the dashboard's own address: a key added at one address works on your workspace address and the main sign-in page of the same domain, but not at a different hostname (such as a custom domain) or an IP address, where the page says Security keys need the dashboard's domain name; they can't be added while you use it by IP address. The list shows the address a key belongs to when it is a different one.

Recovery codes¶

You get 10 recovery codes in the form XXXXX-XXXXX. They are shown once, right after your first second factor is added, and each one signs you in once instead of a code or a key. Account security shows how many remain. Make new recovery codes (it asks for a code from the app, or Use a security key instead) replaces all of them; the earlier codes stop working. Adding another factor later keeps your existing codes. CertIntel stores only a keyed hash of each code.

Signing in¶

After your email and password, the Two-factor sign-in page offers what your account has:

• Use your security key or passkey, when one is registered for this address (at another address the page names the address it belongs to);
• Code from your authenticator app, then Verify. The code changes every 30 seconds; a code is accepted for one step either side of the current one, and each code works only once;
• Use a recovery code instead.

Cancel and sign out abandons the sign-in.

Until the second step succeeds, the password alone gives access to nothing else: the half-finished sign-in expires after 10 minutes. After it, you continue where you were going, including a workspace sign-in handoff and a forced password change.

Signing in with a passkey¶

Sign in with a passkey on the sign-in page needs neither your email nor your password: your browser offers the passkeys it holds for CertIntel, and the passkey unlocked with your fingerprint, face or PIN counts as both steps. It follows the same rules as a password sign-in: the account must be active and not locked, your workspace's IP allow-list applies, and a workspace that requires its own sign-in address sends you there. Security keys added as Security key are only a second step after the password.

Limits and lockout¶

• Five failed attempts per account within five minutes; further attempts are refused until the window passes. A correct code does not count toward this limit.
• Ten failed attempts in a row lock sign-in to the account for 15 minutes and end all of its sessions.
• For an account with two-factor sign-in, a correct password alone no longer clears the count of failed attempts; only a verified second step does.

Failed attempts are recorded in the activity log and raise the auth.warning alert like failed passwords.

Removing a factor or turning it off¶

Under Account security:

• Remove next to a security key or passkey (asks for your password).
• Remove the authenticator app (or Turn off two-factor sign-in when it is your only factor) needs a current code, a recovery code or one of your security keys (Confirm with a security key).

Removing your last second factor turns two-factor sign-in off and drops your recovery codes. While the workspace requires two-factor sign-in you cannot remove your last one; add another factor first (for example a new phone's authenticator app or a new key) and then remove the old one, or ask an administrator to reset it.

Workspace policy¶

Holders of security.update (tenant administrators, or a workspace-wide custom role) set the policy under Security → Two-factor sign-in:

• Optional (the default) - anyone with a password can turn it on for their own account.
• Required - everyone with a password must set it up (an authenticator app, a security key or a passkey). Nobody can turn it off for themselves.

Grace period (days) is 0–30, default 7. It counts from when the policy became required, or from when an account was created if that is later; 0 means straight away. During the grace period, accounts without two-factor sign-in see a reminder banner with the deadline. After it, a local account without two-factor sign-in can only reach Account security until it sets it up, and its API calls are refused with 403 and the problem type mfa-required.

Administrator reset¶

When someone has lost their authenticator app, their security keys or passkeys, and their recovery codes, an administrator can remove their second factors:

• Users → Manage → Reset two-factor, which needs users.update for that user and follows the same rules as a password reset (see who can manage whom). It is refused while acting as another user.
• POST /api/v1/users/{user_id}/mfa/reset, which answers 204.
• On the platform console, Reset two-factor on the tenant's user list.

The reset removes the authenticator app, every security key and passkey and the recovery codes, and signs the user out everywhere. They sign in with their password and can set it up again; under a required policy whose grace period has passed, they are asked to do so at once. You cannot reset your own two-factor sign-in this way (409); use Account security. The Users list marks accounts that use it with a 2FA pill.

API sign-in¶

POST /api/v1/auth/login answers with mfa_required. When it is true, the session cookie it set allows only these calls until the second step succeeds:

Every other call answers 403 with mfa-required. Security keys and passkeys work in the dashboard only: an account without an authenticator app completes this step with a recovery code. Setting up two-factor sign-in has no API; it is done in the dashboard. Automation should use an API key, which two-factor sign-in does not affect.

Activity log¶

Self-hosted settings¶

Security keys and passkeys need the dashboard to be reached by a domain name over HTTPS (or localhost in development). They are tied to the app domain (CERTINTEL_APP_DOMAIN and its aliases, or CERTINTEL_DASHBOARD_DOMAIN), so the apex and every workspace subdomain share them; changing that domain means users add their keys again.

Related pages¶

• Getting started
• Organizations, users & roles
• SSO overview
• API overview
• Troubleshooting