Security

Configure two-factor authentication, manage user sessions, understand rate limiting tiers, and control access security across your Testify platform.

Overview

Testify implements multiple layers of security to protect user accounts and platform data. This includes JWT-based authentication with short-lived tokens, TOTP-based two-factor authentication, active session management, progressive rate limiting, login lockout protection, and email verification.

Two-Factor Authentication (2FA)

Testify supports TOTP (Time-based One-Time Password) for two-factor authentication, compatible with authenticator apps like Google Authenticator, Authy, and Microsoft Authenticator.

Enabling 2FA for Your Account

1. Navigate to "Settings" > "Security"
2. Under "Two-Factor Authentication", click "Enable 2FA"
3. The system generates a secret and displays a QR code
4. Open your authenticator app and scan the QR code
   • Alternatively, manually enter the secret key shown below the QR code
5. Enter the 6-digit code from your authenticator app in the "Verification Code" field
6. Click "Verify and Enable"
7. The system returns a set of backup codes -- save these securely

Tip: Store your backup codes in a password manager or print them and keep them in a safe place. Each backup code can only be used once, and they are your only way to log in if you lose access to your authenticator app.

Logging In with 2FA

1. Enter your email and password as usual
2. After password verification, you are prompted for a "2FA Code"
3. Open your authenticator app and enter the current 6-digit code
4. If the code is valid, you are logged in and receive your access token
5. Alternatively, enter a backup code if you cannot access your authenticator app

Using Backup Codes

If you lose access to your authenticator app:

1. On the 2FA verification screen, click "Use Backup Code"
2. Enter one of your saved backup codes
3. The code is consumed and cannot be used again
4. After logging in, set up 2FA again with a new authenticator device

Disabling 2FA

1. Go to "Settings" > "Security"
2. Click "Disable 2FA"
3. Enter your account password to confirm
4. 2FA is removed from your account

Tip: Only disable 2FA if you need to switch authenticator apps or devices. Re-enable it immediately afterward for maximum security.

2FA Status Check

Users and administrators can check whether 2FA is enabled for an account:

1. Go to "Settings" > "Security"
2. The "Two-Factor Authentication" section shows the current status:
   • Enabled or Disabled
   • When it was enabled
   • Number of remaining backup codes

Session Management

Testify tracks active login sessions and allows users to view and revoke them.

Understanding Sessions

When a user logs in, Testify creates a session record that includes:

• A hashed refresh token
• The user's IP address
• The browser/device user agent
• The login timestamp
• The last active timestamp

Sessions are tied to refresh tokens (30-day validity). Access tokens are short-lived (15 minutes) and refreshed automatically.

Viewing Active Sessions

1. Go to "Settings" > "Security" > "Active Sessions"
2. The list shows all active sessions with:
   • Device/browser information (parsed from user agent)
   • IP address
   • Login date
   • Last activity date
   • Current session indicator

Revoking a Session

To log out a specific device:

1. Go to "Active Sessions"
2. Find the session you want to revoke
3. Click "Revoke"
4. The refresh token for that session is invalidated
5. The device will be logged out when its current access token expires (within 15 minutes)

Revoking All Sessions

To log out all devices except the current one:

1. Go to "Active Sessions"
2. Click "Revoke All Other Sessions"
3. Confirm the action
4. All sessions except the current one are invalidated

Tip: Use "Revoke All Sessions" if you suspect your account has been compromised. Change your password immediately afterward.

Rate Limiting

Testify implements five tiers of rate limiting to protect against abuse and ensure fair resource usage.

Rate Limiting Tiers

Tier	Limit	Window	Applied To
Standard	100 requests	15 minutes	General API endpoints
Auth	10 requests	15 minutes	Login, signup, password reset
AI	20 requests	15 minutes	AI generation, tutoring, chat
Credit	10 requests	1 minute	Credit purchase, wallet operations
Strict	5 requests	15 minutes	Sensitive operations (password change, 2FA)

How Rate Limiting Works

1. Each request is tracked by IP address and user ID (if authenticated)
2. When a user exceeds the limit, they receive a 429 Too Many Requests response
3. The response includes a Retry-After header indicating when they can retry
4. Rate limits reset after the window expires

Rate Limit Headers

Every API response includes rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

Tip: If users report being rate-limited during normal use, check whether automated tools or browser extensions are making excessive API calls.

Login Lockout Protection

Testify protects against brute-force attacks with progressive login lockout.

How Lockout Works

1. After multiple failed login attempts from the same IP or for the same account, the system temporarily locks the account
2. The lockout duration increases with each successive set of failures
3. Successful login clears the failure counter
4. Lockout status is checked before each login attempt

Lockout Thresholds

Failed Attempts	Lockout Duration
5 attempts	1 minute
10 attempts	5 minutes
15 attempts	15 minutes
20+ attempts	30 minutes

Unlocking an Account

As an administrator:

1. Go to "Admin" > "Users"
2. Find the locked-out user
3. Click "Unlock Account"
4. The failed attempt counter is reset

Users can also wait for the lockout period to expire.

Email Verification

New accounts require email verification before they can log in.

Verification Flow

1. User signs up or is created by an admin
2. Testify sends a verification email with a unique token link
3. User clicks the link to verify their email
4. The account is marked as confirmed (confirmed = 1)
5. The user can now log in

Re-sending Verification Email

1. If a user did not receive the verification email, they can click "Resend Verification" on the login page
2. A new verification token is generated and emailed
3. Previous tokens are invalidated

Tip: Invite-based signups (via invite links) skip email verification since the email was already validated through the invite process.

Token Blacklisting

When a user logs out or a session is revoked, the associated tokens are blacklisted to prevent reuse.

How It Works

1. On logout, the current access and refresh tokens are added to the blacklist
2. On session revocation, the refresh token is blacklisted
3. Every authenticated request checks the blacklist before processing
4. Blacklisted tokens are rejected with a 401 Unauthorized response
5. Blacklist entries expire automatically after the token's original expiry time

JWT Token Lifecycle

Understanding the token lifecycle helps troubleshoot authentication issues.

Token Type	Validity	Purpose
Access Token	15 minutes	Authenticates API requests
Refresh Token	30 days	Obtains new access tokens

Token Refresh Flow

1. Client sends a request with an expired access token
2. The server responds with 401 Unauthorized
3. The client sends the refresh token to /auth/v1/refresh
4. If the refresh token is valid and not blacklisted, a new access token is issued
5. The session's last_active timestamp is updated

IP-Based Security

What Is Tracked

• Login attempts are associated with IP addresses
• Rate limiting operates per-IP
• Audit logs record the IP address for each action
• Session records include the login IP

Monitoring Suspicious IPs

1. Go to "Admin" > "Audit Logs"
2. Filter by action type (e.g., failed logins)
3. Look for patterns of failed attempts from the same IP
4. Cross-reference with rate limiting logs

Security Best Practices

For Administrators

1. Enable 2FA on all admin and org owner accounts
2. Review active sessions periodically for unauthorized access
3. Monitor audit logs for suspicious activity (unusual login times, unknown IPs)
4. Set up webhook notifications for security events
5. Keep API keys and secrets rotated on a regular schedule

For Users

1. Enable 2FA on your account
2. Use a strong, unique password (at least 8 characters)
3. Review your active sessions regularly
4. Log out from shared or public computers
5. Do not share your account credentials

For Organizations

1. Enforce email verification for all new accounts
2. Use invite links instead of open signup to control who joins
3. Set appropriate user limits to prevent unauthorized account creation
4. Monitor the audit log for bulk account creation attempts

Troubleshooting

User Cannot Log In After Enabling 2FA

• Verify the authenticator app is synced to the correct time
• Try a backup code
• As an admin, disable 2FA for the user and have them re-enable it

Session Revocation Not Working Immediately

• Access tokens remain valid for up to 15 minutes after session revocation
• The user will be fully logged out once the current access token expires
• For immediate effect, blacklist the access token as well

Rate Limiting Affecting Legitimate Users

• Check if the user is behind a shared IP (corporate proxy, VPN)
• Multiple users behind the same IP share the IP-based rate limit
• Consider increasing rate limits for known corporate IPs via server configuration