Two-Factor Authentication

The GB App uses Laravel Fortify for Two-Factor Authentication (2FA) functionality. Users can enable TOTP-based 2FA using authenticator apps like Google Authenticator or Authy.

Two-Factor Authentication is managed through Laravel Jetstream’s built-in features. The application uses the TwoFactorAuthenticatable trait on the User model.

Enable Two-Factor Authentication

Enable 2FA for the authenticated user.

POST /user/two-factor-authentication

Headers

Authorization

string

required

Bearer token or valid session

X-CSRF-TOKEN

string

required

CSRF token for session-based requests

Response

Returns a 200 status code on success. The user must then retrieve the QR code and recovery codes.

Example Request

curl -X POST https://your-domain.com/user/two-factor-authentication \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-TOKEN: YOUR_CSRF_TOKEN" \
  -H "Accept: application/json"

Get Two-Factor QR Code

Retrieve the QR code for configuring the authenticator app.

GET /user/two-factor-qr-code

Response

svg

string

SVG image of the QR code to scan with authenticator app

Example Request

curl -X GET https://your-domain.com/user/two-factor-qr-code \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "svg": "<svg xmlns='http://www.w3.org/2000/svg' ... >...</svg>"
}

Get Recovery Codes

Retrieve the two-factor authentication recovery codes.

GET /user/two-factor-recovery-codes

Response

recovery_codes

array

Array of recovery codes (typically 8 codes)

Example Request

curl -X GET https://your-domain.com/user/two-factor-recovery-codes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

[
  "abc123-def456",
  "ghi789-jkl012",
  "mno345-pqr678",
  "stu901-vwx234",
  "yza567-bcd890",
  "efg123-hij456",
  "klm789-nop012",
  "qrs345-tuv678"
]

Recovery codes should be stored securely by the user. Each code can only be used once.

Regenerate Recovery Codes

Generate new recovery codes (invalidates existing ones).

POST /user/two-factor-recovery-codes

Headers

Authorization

string

required

Bearer token or valid session

X-CSRF-TOKEN

string

required

CSRF token for session-based requests

Response

Returns new recovery codes in the same format as GET endpoint.

Example Request

curl -X POST https://your-domain.com/user/two-factor-recovery-codes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-TOKEN: YOUR_CSRF_TOKEN" \
  -H "Accept: application/json"

Disable Two-Factor Authentication

Disable 2FA for the authenticated user.

DELETE /user/two-factor-authentication

Headers

Authorization

string

required

Bearer token or valid session

X-CSRF-TOKEN

string

required

CSRF token for session-based requests

Response

Returns a 200 status code on success.

Example Request

curl -X DELETE https://your-domain.com/user/two-factor-authentication \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-TOKEN: YOUR_CSRF_TOKEN" \
  -H "Accept: application/json"

Two-Factor Challenge

When 2FA is enabled, users must complete a two-factor challenge after providing credentials.

Verify with Code

POST /two-factor-challenge

Request Body

code

string

6-digit code from authenticator app

recovery_code

string

One-time recovery code

Example Request (TOTP Code)

curl -X POST https://your-domain.com/two-factor-challenge \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: YOUR_CSRF_TOKEN" \
  -d '{
    "code": "123456"
  }'

Example Request (Recovery Code)

curl -X POST https://your-domain.com/two-factor-challenge \
  -H "Content-Type: application/json" \
  -H "X-CSRF-TOKEN: YOUR_CSRF_TOKEN" \
  -d '{
    "recovery_code": "abc123-def456"
  }'

User Model Fields

The User model includes these 2FA-related fields:

two_factor_confirmed_at

datetime

Timestamp when 2FA was confirmed

Setup Flow

User enables 2FA via POST /user/two-factor-authentication
System generates secret and recovery codes
User retrieves QR code via GET /user/two-factor-qr-code
User scans QR code with authenticator app
User saves recovery codes from GET /user/two-factor-recovery-codes
User confirms 2FA by entering code on next login

Best Practices

Store recovery codes securely - Users should save them in a password manager
Provide backup authentication - Recovery codes ensure account access if device is lost
Time sync important - TOTP codes require accurate system time
Rate limit attempts - Prevent brute force attacks on 2FA codes
Educate users - Provide clear instructions for setup and recovery

Authentication

Reports

Users & Roles

Business APIs

Two-Factor Authentication