The Authentication API provides secure JWT-based authentication with token rotation, two-factor authentication (TOTP), role-based access control, and account lockout protection. All authentication events are recorded in the HIPAA audit log.

Login

Authenticate a user with email and password. Returns JWT access and refresh tokens along with user profile data.

Request Body

Parameter	Type	Required	Description
email	string	Yes	User's email address
password	string	Yes	User's password
totp_code	string	Conditional	6-digit TOTP code (required if 2FA is enabled)

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "clinician@practice.com",
    "password": "SecureP@ss123"
  }'

Response 200 OK

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3MzgyNTY2MDB9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJ0b2tlbl90eXBlIjoicmVmcmVzaCJ9...",
  "user": {
    "id": 1,
    "email": "clinician@practice.com",
    "first_name": "Sarah",
    "last_name": "Johnson",
    "role": "provider",
    "is_2fa_enabled": false
  }
}

Error Response 401 Unauthorized

{
  "detail": "Unable to log in with provided credentials.",
  "code": "authentication_failed"
}

Error Response 423 Locked

{
  "detail": "Account locked due to 5 failed login attempts. Try again in 30 minutes.",
  "code": "account_locked",
  "locked_until": "2026-02-06T15:30:00Z"
}

Token Refresh

Exchange a valid refresh token for a new access token. The refresh token is rotated on each use — the old refresh token is blacklisted and a new one is returned.

Request Body

Parameter	Type	Required	Description
refresh	string	Yes	Current valid refresh token

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response 200 OK

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3MzgyNTc1MDB9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJ0b2tlbl90eXBlIjoicmVmcmVzaF9uZXcifQ..."
}

Logout

Blacklist the current refresh token, effectively logging the user out. The access token remains valid until it expires (15 minutes max) but cannot be refreshed.

Request Body

Parameter	Type	Required	Description
refresh	string	Yes	Refresh token to blacklist

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/logout/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response 204 No Content

Empty response body on successful logout.

Register User

Create a new user account. This endpoint is restricted to admin users only. New users receive a welcome email with their initial credentials.

Request Body

Parameter	Type	Required	Description
email	string	Yes	Valid email address
password	string	Yes	Min 12 chars, 1 upper, 1 lower, 1 digit, 1 special char
first_name	string	Yes	User's first name
last_name	string	Yes	User's last name
role	string	Yes	One of: admin, clinical_manager, provider, nurse, ma, data_monitor, patient

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/register/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@practice.com",
    "password": "S3cur3P@ssw0rd!",
    "first_name": "James",
    "last_name": "Smith",
    "role": "provider"
  }'

Response 201 Created

{
  "id": 5,
  "email": "newuser@practice.com",
  "first_name": "James",
  "last_name": "Smith",
  "role": "provider",
  "is_active": true,
  "created_at": "2026-02-06T14:22:00Z"
}

Get Profile

Retrieve the authenticated user's profile information including role, 2FA status, and last login timestamp.

Example Request

curl https://app.vantrexia.com/api/v1/auth/profile/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK

{
  "id": 1,
  "email": "clinician@practice.com",
  "first_name": "Sarah",
  "last_name": "Johnson",
  "role": "provider",
  "is_2fa_enabled": true,
  "last_login": "2026-02-06T14:00:00Z",
  "date_joined": "2025-11-01T09:00:00Z",
  "is_active": true
}

List Roles

Retrieve the list of available user roles in the system. Useful for populating role dropdowns in registration forms.

Response 200 OK

{
  "roles": [
    { "id": "admin", "name": "Administrator", "description": "Full platform access including user management" },
    { "id": "clinical_manager", "name": "Clinical Manager", "description": "Clinical oversight, triage management, and staff coordination" },
    { "id": "provider", "name": "Provider", "description": "Patient management, triage, and clinical workflows" },
    { "id": "nurse", "name": "Nurse", "description": "Patient monitoring, vitals review, and triage" },
    { "id": "ma", "name": "Medical Assistant", "description": "Patient data entry and basic monitoring" },
    { "id": "data_monitor", "name": "Data Monitor", "description": "Billing management and data monitoring" },
    { "id": "patient", "name": "Patient", "description": "Patient portal access for personal health data" }
  ]
}

Change Password

Change the current user's password. Requires the current password for verification. All existing refresh tokens are blacklisted after a password change.

Request Body

Parameter	Type	Required	Description
old_password	string	Yes	Current password
new_password	string	Yes	New password (min 12 chars, complexity rules apply)
new_password_confirm	string	Yes	Must match new_password

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/password/change/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "OldP@ssword123",
    "new_password": "N3wS3cur3P@ss!",
    "new_password_confirm": "N3wS3cur3P@ss!"
  }'

Response 200 OK

{
  "detail": "Password changed successfully. All sessions have been invalidated."
}

Password Reset

Initiate a password reset for a user by email. A reset link is sent to the registered email address. This endpoint does not require authentication.

Request Body

Parameter	Type	Required	Description
email	string	Yes	Registered email address

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/password-reset/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "clinician@practice.com"
  }'

Response 200 OK

{
  "detail": "Password reset email sent if an account with that email exists."
}

Two-Factor Setup

Generate a TOTP secret and provisioning URI for setting up two-factor authentication. The user scans the QR code with an authenticator app (Google Authenticator, Authy, etc.).

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/2fa/setup/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK

{
  "secret": "JBSWY3DPEHPK3PXP",
  "provisioning_uri": "otpauth://totp/Vantrexia:clinician%40practice.com?secret=JBSWY3DPEHPK3PXP&issuer=Vantrexia",
  "qr_code_url": "/api/v1/auth/2fa/qr-code/",
  "backup_codes": [
    "a1b2c3d4",
    "e5f6g7h8",
    "i9j0k1l2",
    "m3n4o5p6",
    "q7r8s9t0"
  ]
}

Two-Factor Verify

Verify and activate two-factor authentication using a TOTP code from the authenticator app. This must be called after /auth/2fa/setup/ to confirm the user has correctly configured their app.

Request Body

Parameter	Type	Required	Description
totp_code	string	Yes	6-digit TOTP code from authenticator app

Example Request

curl -X POST https://app.vantrexia.com/api/v1/auth/2fa/verify/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "totp_code": "482913"
  }'

Response 200 OK

{
  "detail": "Two-factor authentication enabled successfully.",
  "is_2fa_enabled": true
}

Error Response 400 Bad Request

{
  "detail": "Invalid TOTP code. Please try again.",
  "code": "invalid_totp"
}