Two-Factor Authentication

Pocket Alert supports TOTP two-factor authentication on both the web dashboard and the mobile app. Once enabled, a password alone no longer gets anyone into your account.

Set it up under Account → Security.

Setting it up

1. Open Account → Security and start the setup. You get a QR code and a secret.
2. Scan it with any TOTP authenticator — Google Authenticator, 1Password, Authy, Bitwarden.
3. Enter the six-digit code to confirm. Only after a correct code does 2FA actually switch on.
4. Save the recovery codes you are shown. Each one works once.

Interrupted setup is safe

Starting a new setup does not touch your existing 2FA. The new secret sits in a pending slot and only replaces the active one after you confirm a code — so closing the tab halfway cannot lock you out.

How login changes

With 2FA enabled, POST /v1/auth/login no longer returns a JWT. It returns a short-lived challenge:

{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}

Exchange the challenge plus a code for the real token:

POST https://api.pocketalert.app/v1/auth/2fa/login

curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'

A successful exchange returns the same payload a normal login would — token, name, email, avatar. The code field accepts either a six-digit TOTP code or one of your recovery codes.

Challenges live for 5 minutes.

API keys are unaffected

Scripts keep working

2FA applies to interactive logins. API keys from API Keys authenticate with the Token header and are not challenged — your cron jobs, CI pipelines and monitoring hooks keep sending alerts exactly as before.

This is also why API keys are worth scoping per service: revoking one does not disturb the others.

Recovery codes

Recovery codes are single-use and consumed atomically — two parallel logins cannot spend the same code. Generate a fresh set at any time from Account → Security; issuing new codes invalidates the old ones.

Lost both your authenticator and your codes? Contact support. There is no self-service bypass, which is the point.

Brute-force protection

Five failed codes lock the account for 15 minutes and further attempts return 429. The counter resets on a successful login, and on enabling or disabling 2FA. Because a challenge stays valid for its full five minutes, this attempt limit — not the challenge lifetime — is what makes guessing a six-digit code impractical.

Email notifications

You get an email whenever 2FA is enabled or disabled on your account. If one arrives and it was not you, that is your signal to change the password immediately.

Endpoints

Method	Endpoint	Purpose
GET	/v1/auth/2fa/status	Whether 2FA is enabled, and how many recovery codes remain
POST	/v1/auth/2fa/setup	Start enrollment — returns secret and QR payload
POST	/v1/auth/2fa/enable	Confirm a code and activate 2FA
POST	/v1/auth/2fa/disable	Turn 2FA off — requires a code and your password
POST	/v1/auth/2fa/recovery-codes	Issue a fresh set of recovery codes
POST	/v1/auth/2fa/login	Exchange challenge + code for a JWT (no auth header)

Every endpoint except /auth/2fa/login requires an authenticated session.

Related

• Login — the first step of the login flow
• Introduction — authentication overview