Documentation Index
Fetch the complete documentation index at: https://docs.gurubase.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Two-factor authentication (2FA) adds a second step to login. After entering your password, you also enter a 6-digit code from an authenticator app. Gurubase uses standard TOTP (RFC 6238), so any authenticator app works (Google Authenticator, Authy, 1Password, Microsoft Authenticator, and others). 2FA is available to every authenticated user on both Gurubase Cloud and self-hosted deployments.Enabling 2FA
Open the Security page
Open your account menu and select Security, or go to
/account/security. The Two-Factor Authentication section lets you add a second step to your login using an authenticator app.Scan the QR code
Scan the QR code with your authenticator app, then enter the 6-digit code it shows. If you cannot scan, use Copy secret to enter the key manually. Click Verify and enable.
The setup session expires after 10 minutes. If it expires, start enrollment again to get a fresh QR code.
Signing in with 2FA
Once 2FA is enabled, signing in asks for a 6-digit code after your password. Enter the current code from your authenticator app, or use one of your backup codes if you cannot reach the app. A verified session stays trusted for 12 hours by default before a code is requested again.Backup codes
Backup codes are single-use. To issue a fresh set, open the Security page and click Regenerate, then enter your current authenticator code. Your previous backup codes stop working as soon as new ones are generated.Disabling 2FA
On the Security page, click Disable 2FA. After 2FA is disabled, login no longer asks for a verification code.Self-hosted configuration
2FA works out of the box on self-hosted deployments. The following environment variables let operators tune it:| Variable | Default | Description |
|---|---|---|
TOTP_ENCRYPTION_KEY | derived from SECRET_KEY | Fernet key (32 url-safe base64-encoded bytes) used to encrypt TOTP secrets at rest. If unset, a key is derived from SECRET_KEY. |
TWOFA_SESSION_TTL_SECONDS | 43200 (12 hours) | How long a verified 2FA session stays trusted before a code is requested again. |
TWOFA_ISSUER_NAME | Gurubase | Issuer name shown next to the account in the authenticator app. |
TWOFA_REDIS_DB | 2 | Dedicated Redis database index for 2FA session keys and pending setup secrets. |
If
TOTP_ENCRYPTION_KEY is not set, Gurubase derives a key from SECRET_KEY and logs a warning. Set a stable, dedicated TOTP_ENCRYPTION_KEY in production so existing 2FA enrollments keep working if SECRET_KEY ever changes.