Skip to main content

Auth Endpoints

Authentication endpoints for login, logout, and session management.

Login​

Authenticate a user and receive tokens.

POST /api/v1/auth/login

Request Body​

{
  "username": "admin",
  "password": "your_password"
}

Response​

Success (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "Admin"
  }
}

MFA Required (200):

{
  "mfa_required": true,
  "mfa_token": "mfa_challenge_abc123"
}

Example​

curl -X POST "https://bloqd.example.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password"
  }'

MFA Verify​

Complete MFA verification after login.

POST /api/v1/auth/mfa/verify

Request Body​

{
  "mfa_token": "mfa_challenge_abc123",
  "code": "123456"
}

Response​

Success (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": {
    "id": 1,
    "username": "admin",
    "role": "Admin"
  }
}

Refresh Token​

Get a new access token using refresh token.

POST /api/v1/auth/refresh

Request Body​

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response​

Success (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

Logout​

Invalidate current session.

POST /api/v1/auth/logout

Headers​

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response​

Success (200):

{
  "message": "Logged out successfully"
}

Get Current User​

Get information about the authenticated user.

GET /api/v1/auth/me

Headers​

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response​

Success (200):

{
  "id": 1,
  "username": "admin",
  "email": "admin@example.com",
  "role": "Admin",
  "mfa_enabled": true,
  "created_at": "2024-01-01T00:00:00Z",
  "last_login": "2024-01-15T10:30:00Z"
}

Enable MFA​

Enable MFA for the current user.

POST /api/v1/auth/mfa/enable

Headers​

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response​

Success (200):

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,...",
  "backup_codes": [
    "12345678",
    "23456789",
    "34567890"
  ]
}

Confirm MFA Enable​

Confirm MFA setup with verification code.

POST /api/v1/auth/mfa/confirm

Headers​

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Request Body​

{
  "code": "123456"
}

Response​

Success (200):

{
  "message": "MFA enabled successfully",
  "mfa_enabled": true
}

Disable MFA​

Disable MFA for the current user.

POST /api/v1/auth/mfa/disable

Headers​

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Request Body​

{
  "password": "your_password"
}

Response​

Success (200):

{
  "message": "MFA disabled successfully",
  "mfa_enabled": false
}

Change Password​

Change the current user's password.

POST /api/v1/auth/password

Headers​

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Request Body​

{
  "current_password": "old_password",
  "new_password": "new_secure_password"
}

Response​

Success (200):

{
  "message": "Password changed successfully"
}

OAuth Login (GitHub)​

Initiate GitHub OAuth flow.

GET /api/v1/auth/github

Response​

Redirects to GitHub for authentication.

OAuth Callback (GitHub)​

Handle GitHub OAuth callback.

GET /api/v1/auth/github/callback?code=xxx&state=xxx

Response​

Redirects to dashboard with session cookie set.

OAuth Login (Google)​

Initiate Google OAuth flow.

GET /api/v1/auth/google

Response​

Redirects to Google for authentication.

OAuth Callback (Google)​

Handle Google OAuth callback.

GET /api/v1/auth/google/callback?code=xxx&state=xxx

Response​

Redirects to dashboard with session cookie set.