Authentication API

The Authentication API provides endpoints for user authentication, token management, and password operations.

Endpoints

Request OTP

POST /authentication/request-otp

Verifies username and password, then sends an OTP if two-factor authentication is enabled. If 2FA is disabled, returns access and refresh tokens directly.

Request Body

{
  "username": "string",  // User code
  "password": "string"   // User password
}

Responses

200 OK - Authentication successful

If 2FA is disabled:

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "bearer"
}

If 2FA is enabled:

{
  "detail": "OTP sent to your email",
  "expires_in": 180  // seconds
}

404 Not Found - Invalid credentials

{
  "detail": "Invalid User Code"
}

or

{
  "detail": "Invalid User Password"
}

403 Forbidden - Inactive account

{
  "detail": "Activate your account to access this resource"
}

Resend OTP

POST /authentication/resend-otp

Resends the OTP if the previous one has expired.

Request Body

{
  "username": "string"  // User code
}

Responses

200 OK - OTP resent

{
  "detail": "OTP resent to your email",
  "expires_in": 180  // seconds
}

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Inactive account

{
  "detail": "Activate your account to access this resource"
}

Verify OTP

POST /authentication/verify-otp

Verifies the OTP and returns access and refresh tokens if valid.

Request Body

{
  "username": "string",  // User code
  "otp": "string"        // One-time password
}

Responses

200 OK - OTP verified

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "bearer"
}

400 Bad Request - Invalid OTP

{
  "detail": "Invalid OTP"
}

400 Bad Request - Expired OTP

{
  "detail": "OTP has expired. Please request a new one."
}

404 Not Found - User not found

{
  "detail": "User not found"
}

Refresh Token

POST /authentication/refresh-token

Uses a refresh token to obtain a new access token.

Request Body

{
  "refresh_token": "string"
}

Responses

200 OK - Token refreshed

{
  "access_token": "string",
  "token_type": "bearer"
}

401 Unauthorized - Invalid refresh token

{
  "detail": "Invalid refresh token"
}

401 Unauthorized - Expired refresh token

{
  "detail": "Refresh token has expired"
}

Reset Password

POST /authentication/reset-password/{user_id}

Resets a user's password and sends the new password via email. Requires the reset_password permission.

Path Parameters

user_id (UUID): ID of the user whose password will be reset

Responses

200 OK - Password reset

{
  "detail": "Password reset successfully. Please check your email for the new password."
}

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Change Password

PUT /authentication/change-password

Changes the current user's password. Requires the change_password permission.

Request Body

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

Responses

200 OK - Password changed

{
  "detail": "Password changed successfully"
}

400 Bad Request - Incorrect current password

{
  "detail": "Incorrect current password"
}

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Authentication Flow

Standard Authentication (without 2FA)

Client sends username and password to /authentication/request-otp
Server validates credentials and returns access and refresh tokens
Client includes the access token in the Authorization header for subsequent requests
When the access token expires, client uses the refresh token to get a new access token

Two-Factor Authentication (with 2FA)

Client sends username and password to /authentication/request-otp
Server validates credentials and sends an OTP to the user's email
Client prompts user for the OTP and sends it to /authentication/verify-otp
Server validates the OTP and returns access and refresh tokens
Client includes the access token in the Authorization header for subsequent requests
When the access token expires, client uses the refresh token to get a new access token

Token Format

Access Token

The access token is a JWT with the following claims:

sub: User code
user_id: User ID
is_active: Whether the user account is active
exp: Expiration time
type: Token type ("access")

Refresh Token

The refresh token is a JWT with the following claims:

sub: User code
user_id: User ID
exp: Expiration time
type: Token type ("refresh")

Security Considerations

Access tokens are valid for 30 minutes
Refresh tokens are valid for 7 days
OTPs are valid for 3 minutes
All passwords are hashed using bcrypt
JWT tokens are signed using HS256 algorithm
Two-factor authentication is optional but recommended