Authentication Documentation
Nuxera AI Authentication API
Secure access to Nuxera AI services requires proper authentication. This page describes how to obtain and use authentication tokens for accessing Nuxera API endpoints.
Format Support
Nuxera AI supports multiple response/request formats to accommodate different healthcare system requirements:
- JSON (default): Standard API responses/requests
- HL7: Healthcare interoperability standard
- FHIR: Fast Healthcare Interoperability Resources standard
To request a specific format, include the x-response-format header in your request:
x-response-format: hl7
x-response-format: fhir
Note: If no format header is specified, responses default to JSON format.
To send request in a specific format, include the x-request-format header in your request:
x-request-format: hl7
x-request-format: fhir
Note: If the x-request-format header is not provided, the request will be processed as JSON by default.
Login
Endpoint: /api/auth/login
Method: POST
Description: This endpoint allows users to authenticate and obtain an access token for further interactions with the Nuxera AI APIs.
Request Body
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| username | string | Yes | The user's username or email address |
| password | string | Yes | The user's password |
Response
Success (200 OK)
The response includes:
- token: A JWT access token that should be used for subsequent API requests (expires in 15 minutes)
- refreshToken: A refresh token used to obtain new access tokens (expires in 30 days)
- expiresAt: ISO timestamp when the access token expires
- refreshTokenExpiresAt: ISO timestamp when the refresh token expires
- user: Basic information about the authenticated user
Error (401 Unauthorized)
{
"error": "Authentication failed",
"message": "Invalid username or password"
}
Get User Information
Endpoint: /api/auth/me
Method: GET
Description: This endpoint retrieves information about the currently authenticated user. Requires a valid authentication token.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Bearer token from login |
Response
Success (200 OK)
Error (401 Unauthorized)
{
"error": "Authentication required",
"message": "Invalid or missing authentication token"
}
Refresh Token
Endpoint: /api/auth/refresh
Method: POST
Description: This endpoint allows you to obtain a new access token using a valid refresh token. This implements refresh token rotation for enhanced security.
Request Body
{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| refreshToken | string | Yes | The valid refresh token |
Response
Success (200 OK)
The response includes:
- token: A new JWT access token (expires in 15 minutes)
- refreshToken: A new refresh token (expires in 30 days)
- expiresAt: ISO timestamp when the access token expires
- refreshTokenExpiresAt: ISO timestamp when the refresh token expires
- user: Basic user information
Error (400 Bad Request)
{
"error": "refreshToken is required"
}
Error (401 Unauthorized)
{
"error": "Invalid refresh token"
}
Error (401 Unauthorized)
{
"error": "Refresh token expired"
}
Error (401 Unauthorized)
{
"error": "User not found"
}
Error (401 Unauthorized)
{
"error": "User account is not active"
}
Change Password
Endpoint: /api/auth/change-password
Method: POST
Description: This endpoint allows authenticated users to change their password. Requires the current password for verification.
Request Body
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| currentPassword | string | Yes | The user's current password |
| newPassword | string | Yes | The new password to set |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Bearer token from login |
Response
Success (200 OK)
Error (400 Bad Request)
{
"error": "Invalid current password",
"message": "The current password provided is incorrect"
}
Error (401 Unauthorized)
{
"error": "Authentication required",
"message": "Invalid or missing authentication token"
}
Using the Authentication Token
Once you have obtained an authentication token, you must include it in all subsequent API requests in the Authorization header as a Bearer token:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Token Expiration
Access tokens are valid for 15 minutes after issuance. Refresh tokens are valid for 30 days. When an access token expires, you can use the refresh token to obtain a new access token without requiring the user to log in again. After the refresh token expires, you'll need to request new tokens by calling the login endpoint again.
Security Best Practices
- Never expose authentication tokens in client-side code
- Store tokens securely on your server
- Implement proper error handling for expired or invalid tokens
- Do not share tokens between different applications or users
Example Usage
Next Steps
Now that you understand how to authenticate with the Nuxera AI API, proceed to:
- Transcription API - Learn how to transcribe medical consultations
- Dictation API - Learn how to process medical dictations