Authentication API Reference¶

The Authentication API provides secure user registration, login, and session management for the Federated Learning Platform using JWT tokens and role-based access control.

Base URL¶

http://localhost:8000/auth

Authentication Flow¶

sequenceDiagram
    participant Client
    participant Frontend
    participant Backend
    participant Database
    participant JWT

    Client->>Frontend: Enter credentials
    Frontend->>Backend: POST /auth/login
    Backend->>Database: Validate user
    Database-->>Backend: User data
    Backend->>JWT: Generate token
    JWT-->>Backend: Access token
    Backend-->>Frontend: Token + user info
    Frontend->>Frontend: Store token

    Note over Client,JWT: Subsequent API calls

    Frontend->>Backend: API request + Bearer token
    Backend->>JWT: Validate token
    JWT-->>Backend: Token claims
    Backend-->>Frontend: API response

Endpoints¶

POST /auth/register¶

Register a new user account.

Request¶

Headers:

Content-Type: application/json

Body:

{
  "username": "string",
  "email": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "organization": "string"
}

Validation Rules: - username: 3-50 characters, alphanumeric and underscores only - email: Valid email format - password: Minimum 8 characters, must contain uppercase, lowercase, digit, and special character - first_name, last_name: 1-100 characters - organization: Optional, 1-200 characters

Response¶

Success (201 Created):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "johndoe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "organization": "Example Corp",
    "roles": ["user"],
    "created_at": "2024-01-01T00:00:00Z",
    "is_active": true
  },
  "message": "User registered successfully",
  "timestamp": "2024-01-01T00:00:00Z"
}

Error (400 Bad Request):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "email",
      "reason": "Email already exists"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Example¶

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "SecurePass123!",
    "first_name": "John",
    "last_name": "Doe",
    "organization": "Example Corp"
  }'

POST /auth/login¶

Authenticate user and receive access token.

Request¶

Headers:

Content-Type: application/json

Body:

{
  "username": "string",
  "password": "string",
  "mfa_token": "string"
}

Parameters: - username: Username or email address - password: User password - mfa_token: Optional MFA token (required if MFA is enabled)

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "johndoe",
      "email": "john@example.com",
      "roles": ["user"],
      "permissions": ["read:projects", "write:projects", "start:training"]
    }
  },
  "message": "Login successful",
  "timestamp": "2024-01-01T00:00:00Z"
}

MFA Required (200 OK):

{
  "success": true,
  "data": {
    "requires_mfa": true,
    "temp_token": "temp_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "mfa_methods": ["totp", "sms"]
  },
  "message": "MFA token required",
  "timestamp": "2024-01-01T00:00:00Z"
}

Error (401 Unauthorized):

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid username or password",
    "details": {
      "attempts_remaining": 4,
      "lockout_time": null
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Example¶

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "SecurePass123!"
  }'

POST /auth/refresh¶

Refresh access token using refresh token.

Request¶

Headers:

Content-Type: application/json

Body:

{
  "refresh_token": "string"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "Token refreshed successfully",
  "timestamp": "2024-01-01T00:00:00Z"
}

Example¶

curl -X POST http://localhost:8000/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

POST /auth/logout¶

Invalidate current session and tokens.

Request¶

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Body:

{
  "refresh_token": "string"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {},
  "message": "Logout successful",
  "timestamp": "2024-01-01T00:00:00Z"
}

Example¶

curl -X POST http://localhost:8000/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

GET /auth/me¶

Get current user information.

Request¶

Headers:

Authorization: Bearer <access_token>

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "johndoe",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "organization": "Example Corp",
    "roles": ["user"],
    "permissions": ["read:projects", "write:projects", "start:training"],
    "created_at": "2024-01-01T00:00:00Z",
    "last_login": "2024-01-01T12:00:00Z",
    "is_active": true,
    "mfa_enabled": false
  },
  "message": "User information retrieved",
  "timestamp": "2024-01-01T00:00:00Z"
}

Example¶

curl -X GET http://localhost:8000/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

PUT /auth/profile¶

Update user profile information.

Request¶

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Body:

{
  "first_name": "string",
  "last_name": "string",
  "organization": "string",
  "email": "string"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "organization": "New Organization",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "message": "Profile updated successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

Example¶

curl -X PUT http://localhost:8000/auth/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "organization": "New Organization"
  }'

POST /auth/change-password¶

Change user password.

Request¶

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Body:

{
  "current_password": "string",
  "new_password": "string",
  "confirm_password": "string"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {},
  "message": "Password changed successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

Example¶

curl -X POST http://localhost:8000/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPass123!",
    "new_password": "NewSecurePass456!",
    "confirm_password": "NewSecurePass456!"
  }'

Multi-Factor Authentication¶

POST /auth/mfa/setup¶

Setup MFA for user account.

Request¶

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Body:

{
  "method": "totp"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "backup_codes": [
      "12345678",
      "87654321",
      "11223344"
    ]
  },
  "message": "MFA setup initiated",
  "timestamp": "2024-01-01T12:00:00Z"
}

POST /auth/mfa/verify¶

Verify and enable MFA.

Request¶

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Body:

{
  "token": "123456"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "mfa_enabled": true
  },
  "message": "MFA enabled successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

POST /auth/mfa/disable¶

Disable MFA for user account.

Request¶

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Body:

{
  "password": "string",
  "token": "123456"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {
    "mfa_enabled": false
  },
  "message": "MFA disabled successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

Password Reset¶

POST /auth/forgot-password¶

Request password reset.

Request¶

Headers:

Content-Type: application/json

Body:

{
  "email": "string"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {},
  "message": "Password reset email sent",
  "timestamp": "2024-01-01T12:00:00Z"
}

POST /auth/reset-password¶

Reset password using reset token.

Request¶

Headers:

Content-Type: application/json

Body:

{
  "token": "string",
  "new_password": "string",
  "confirm_password": "string"
}

Response¶

Success (200 OK):

{
  "success": true,
  "data": {},
  "message": "Password reset successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

JWT Token Structure¶

Access Token Claims¶

{
  "sub": "johndoe",
  "user_id": "507f1f77bcf86cd799439011",
  "email": "john@example.com",
  "roles": ["user"],
  "permissions": ["read:projects", "write:projects", "start:training"],
  "iat": 1640995200,
  "exp": 1640998800,
  "type": "access",
  "jti": "unique-token-id"
}

Refresh Token Claims¶

{
  "sub": "johndoe",
  "user_id": "507f1f77bcf86cd799439011",
  "iat": 1640995200,
  "exp": 1641599999,
  "type": "refresh",
  "jti": "unique-refresh-token-id"
}

Error Codes¶

Code	Description	HTTP Status
`VALIDATION_ERROR`	Input validation failed	400
`AUTHENTICATION_FAILED`	Invalid credentials	401
`TOKEN_EXPIRED`	JWT token has expired	401
`TOKEN_INVALID`	JWT token is malformed or invalid	401
`MFA_REQUIRED`	Multi-factor authentication required	401
`MFA_INVALID`	Invalid MFA token	401
`ACCOUNT_LOCKED`	Account temporarily locked	423
`ACCOUNT_DISABLED`	Account has been disabled	403
`PERMISSION_DENIED`	Insufficient permissions	403
`USER_EXISTS`	Username or email already exists	409
`USER_NOT_FOUND`	User account not found	404
`RATE_LIMIT_EXCEEDED`	Too many requests	429

Rate Limiting¶

Authentication endpoints have specific rate limits:

Endpoint	Rate Limit	Window
`/auth/login`	5 requests	1 minute
`/auth/register`	3 requests	5 minutes
`/auth/forgot-password`	3 requests	15 minutes
`/auth/refresh`	10 requests	1 minute
Other endpoints	20 requests	1 minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1640995260

Security Considerations¶

Password Requirements¶

Minimum 8 characters
At least one uppercase letter
At least one lowercase letter
At least one digit
At least one special character
Cannot be a common password
Cannot contain username or email

Token Security¶

Access tokens expire in 30 minutes
Refresh tokens expire in 7 days
Tokens are invalidated on logout
Failed login attempts are tracked and logged
Account lockout after 5 failed attempts

HTTPS Requirements¶

All authentication endpoints must be accessed over HTTPS in production:

Strict-Transport-Security: max-age=31536000; includeSubDomains

Next: Continue to Training API for federated learning management endpoints.