Two-Factor (TOTP)

Thogits supports two-factor authentication using TOTP (Time-based One-Time Passwords), compatible with authenticator apps like Google Authenticator, Authy, and 1Password.

Setup Flow

1. Generate secret: Call the setup endpoint to get a TOTP secret and QR code.
2. Scan QR code: Add the account to your authenticator app by scanning the QR code or manually entering the base32 secret.
3. Confirm: Enter a 6-digit code from your authenticator app to confirm setup.

Once confirmed, all future email/password logins will require a TOTP code after the password step.

---

POST /auth/2fa/totp/setup

Generate a new TOTP secret and QR code for setup.

Auth required: Yes

curl -X POST https://app.thogits.com/api/auth/2fa/totp/setup \
  -b cookies.txt -c cookies.txt

Response (200):

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,iVBORw0KGgo..."
}

Field	Type	Description
secret	string	Base32-encoded TOTP secret (for manual entry in authenticator apps)
qr_code	string	Data URI of a PNG QR code image (for scanning)

Note

The secret is not yet active. You must confirm it with a valid code before TOTP enforcement begins.

---

POST /auth/2fa/totp/confirm

Confirm TOTP setup by providing a valid 6-digit code from your authenticator app. This activates two-factor authentication on the account.

Auth required: Yes

Request body:

Field	Type	Required	Description
code	string	Yes	6-digit TOTP code from your authenticator app

curl -X POST https://app.thogits.com/api/auth/2fa/totp/confirm \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"code": "123456"}'

Response (200):

{"message": "TOTP confirmed"}

Errors:

Status	Cause
400	Invalid code or no pending TOTP setup

---

POST /auth/2fa/totp/verify

Verify a TOTP code during login. This endpoint is called after a password login returns {"needs_2fa": true}.

Auth required: Partial session (post-password, pre-2FA)

Request body:

Field	Type	Required	Description
code	string	Yes	6-digit TOTP code

# Step 1: Login returns needs_2fa
curl -X POST https://app.thogits.com/api/auth/login \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"email": "user@example.com", "password": "securepass123"}'
# Response: {"needs_2fa": true}

# Step 2: Complete login with TOTP code
curl -X POST https://app.thogits.com/api/auth/2fa/totp/verify \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"code": "654321"}'

Response (200): The full UserInfo object (login is now complete).

Errors:

Status	Cause
400	Invalid code
401	No partial session (must call login first)

---

POST /auth/2fa/totp/disable

Disable TOTP two-factor authentication. Requires a valid TOTP code if TOTP is currently confirmed and active.

Auth required: Yes

Request body:

Field	Type	Required	Description
code	string	Conditional	Required if TOTP is currently active (confirmed). Not required if setup was started but never confirmed.

curl -X POST https://app.thogits.com/api/auth/2fa/totp/disable \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"code": "789012"}'

Response (200):

{"message": "TOTP disabled"}

Errors:

Status	Cause
400	Invalid code (when TOTP is active and code is required)