API Reference

Create a new account. With mandatory two-factor authentication, the response carries a short-lived mfa_token instead of a session token — complete the enrollment flow below before any session exists.

{
  "email": "you@example.com",
  "password": "yourpassword1"
}

{
  "mfa_required": true,
  "mfa_token": "<short-lived_token>",
  "needs_setup": true,
  "token_type": "bearer"
}

Log in with your credentials. The password is only the first factor: when 2FA is required (and for every MFA-enabled account) you get a second-factor step, not a session token.

{
  "email": "you@example.com",
  "password": "yourpassword1"
}

{
  "mfa_required": true,
  "mfa_token": "<short-lived_token>",
  "needs_setup": false,
  "token_type": "bearer"
}

curl -X POST https://www.torrentcdn.store/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpassword1"}'
# → {"mfa_required":true,"mfa_token":"<mfa>","needs_setup":false,"token_type":"bearer"}

Mandatory two-factor authentication

Begin enrollment. Mints a TOTP secret, its otpauth URI, and 10 single-use backup codes. Authenticated by the short-lived mfa_token (mid-signup / mid-login, when no session exists yet) or by your session token (dashboard). The backup codes are returned in plaintext exactly once — save them before leaving this step.

Headers:
  Authorization: Bearer <mfa_token>

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_uri": "otpauth://totp/TorrentCDN:you@example.com?secret=JBSWY3DPEHPK3PXP&issuer=TorrentCDN",
  "backup_codes": ["ABC1234567", "DEF2345678", "GHI3456789"]
}

Complete the second factor: present the mfa_token plus a valid 6-digit TOTP code (or a single-use backup code) to receive your real session token. When the account had no 2FA yet, confirming also enrolls it — this is how signup and mandatory-login enrollment finish.

{
  "mfa_token": "<short-lived_token>",
  "code": "123456"
}

{
  "access_token": "<your_access_token>",
  "token_type": "bearer"
}

# 1. Create the account — no session yet, just an mfa_token
curl -X POST https://www.torrentcdn.store/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpassword1"}'
# → {"mfa_required":true,"mfa_token":"<mfa>","needs_setup":true,"token_type":"bearer"}

# 2. Enroll — returns the secret + backup codes (shown once)
curl -X POST https://www.torrentcdn.store/auth/mfa/setup \
  -H "Authorization: Bearer <mfa>"

# 3. Confirm with a code from your authenticator app → real session
curl -X POST https://www.torrentcdn.store/auth/mfa/confirm \
  -H "Content-Type: application/json" \
  -d '{"mfa_token":"<mfa>","code":"123456"}'

Lost your authenticator?

The single-use backup codes shown at enrollment are your recovery path — each can be entered at login exactly once. If you lose both the app and every backup code, the account cannot sign in: two-factor authentication is enforced for every account and cannot be removed with a password alone (by design, so a stolen password can never strip 2FA). Contact support with proof of account ownership to have two-factor authentication reset.