API Documentation

Complete API reference for the Laravel 2FA authentication system

API Overview

Authentication

Laravel Sanctum token-based authentication

2FA Protection

Two-factor authentication for enhanced security

JSON Responses

Consistent JSON API responses

Authentication Endpoints

POST /api/auth/login

Authenticate user and return access token

Request Body

{
  "email": "user@example.com",
  "password": "password"
}

Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      "is_2fa_enabled": false
    },
    "token": "1|abc123...",
    "requires_2fa": false
  }
}
POST /api/auth/logout

Logout user and invalidate token

Headers

Authorization: Bearer {token}
Accept: application/json

Response

{
  "success": true,
  "message": "Logged out successfully"
}
GET /api/auth/user

Get authenticated user information

Headers

Authorization: Bearer {token}
Accept: application/json

Response

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      "is_2fa_enabled": true,
      "created_at": "2024-01-01T00:00:00.000000Z"
    }
  }
}

Two-Factor Authentication

POST /api/2fa/setup

Generate 2FA secret and QR code

Headers

Authorization: Bearer {token}
Accept: application/json

Response

{
  "success": true,
  "message": "2FA setup initiated",
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "qr_url": "otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"
  }
}
POST /api/2fa/confirm

Confirm 2FA setup with verification code

Request Body

{
  "code": "123456"
}

Response

{
  "success": true,
  "message": "2FA enabled successfully"
}
POST /api/2fa/verify

Verify 2FA code for protected routes

Request Body

{
  "code": "123456"
}

Response

{
  "success": true,
  "message": "2FA verification successful"
}
GET /api/2fa/status

Get 2FA status for current user

Headers

Authorization: Bearer {token}
Accept: application/json

Response

{
  "success": true,
  "data": {
    "is_2fa_enabled": true,
    "is_2fa_verified": false
  }
}
POST /api/2fa/disable

Disable 2FA for current user

Request Body

{
  "code": "123456"
}

Response

{
  "success": true,
  "message": "2FA disabled successfully"
}

Protected Routes

Routes protected by 2FA middleware require both authentication and 2FA verification.

Example Protected Route

Route::middleware(['auth:sanctum', '2fa.verified'])
    ->get('/api/protected', [ProtectedController::class, 'index']);

Error Response

{
  "success": false,
  "message": "2FA verification required",
  "error": "2fa_required"
}

Error Codes

Code Message Description
401 Unauthorized Invalid or missing authentication token
403 Forbidden 2FA verification required
422 Validation Error Invalid input data
2fa_required 2FA Required Two-factor authentication is required
invalid_totp Invalid TOTP Invalid or expired TOTP code
setup_expired Setup Expired 2FA setup session has expired

Testing the API

Using cURL

# Login
curl -X POST http://localhost/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password"}'

# Use returned token
curl -X GET http://localhost/api/auth/user \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Using Postman

  1. 1. Create a new collection
  2. 2. Set base URL: http://localhost
  3. 3. Add Authorization header: Bearer {token}
  4. 4. Set Accept header: application/json
  5. 5. Test endpoints with the provided examples