Authentication API

The Authentication API handles user login, token management, and multi-factor authentication.

Endpoints

Login

Authenticate a user and receive access tokens.

POST /auth/login

Request Body:

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

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "retailer"
  }
}

Refresh Token

Get a new access token using a refresh token.

POST /auth/refresh

Request Body:

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

Logout

Invalidate the current session.

POST /auth/logout
Authorization: Bearer {access_token}

Get Current User

Retrieve the authenticated user's profile.

GET /auth/me
Authorization: Bearer {access_token}

Response:

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "retailer",
  "entity_id": "entity-uuid",
  "permissions": ["read:inventory", "write:orders"],
  "mfa_enabled": true
}

Multi-Factor Authentication (MFA)

Enable MFA

POST /auth/mfa/enable
Authorization: Bearer {access_token}

Response:

{
  "secret": "BASE32SECRET",
  "qr_code_url": "otpauth://totp/ReUp:user@example.com?secret=..."
}

Verify MFA

POST /auth/mfa/verify
Authorization: Bearer {access_token}

{
  "code": "123456"
}

MFA Login

When MFA is enabled, login returns a partial token:

POST /auth/login

Response (MFA Required):

{
  "mfa_required": true,
  "temp_token": "temporary-token"
}

Complete login with MFA code:

POST /auth/mfa/complete
{
  "temp_token": "temporary-token",
  "code": "123456"
}

Password Management

Request Password Reset

POST /auth/password/reset-request
{
  "email": "user@example.com"
}

Reset Password

POST /auth/password/reset
{
  "token": "reset-token-from-email",
  "new_password": "newSecurePassword123"
}

Change Password

POST /auth/password/change
Authorization: Bearer {access_token}

{
  "current_password": "oldPassword",
  "new_password": "newPassword123"
}

Error Codes

Code	Description
INVALID_CREDENTIALS	Wrong email or password
ACCOUNT_LOCKED	Too many failed attempts
MFA_REQUIRED	MFA verification needed
INVALID_MFA_CODE	Wrong MFA code
TOKEN_EXPIRED	Token has expired
TOKEN_INVALID	Token is malformed