Nuxera
|
API Keys

Api keys Documentation

API Keys Management

API Keys are required for all AI Medical Note transcription calls. This documentation covers the complete API Keys management system.

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.

Overview

The API Keys system allows users to:

  • Create and manage API keys for authentication
  • Control access to transcription services
  • Pause/resume keys as needed
  • Set default keys for easier usage
  • Monitor key usage and expiry

Authentication

All API Keys management endpoints require JWT authentication.

Authorization: Bearer <your_jwt_token>

Base URL

https://nuxera.cloud/api/apiKeys

Endpoints

Create API Key

Creates a new API key for the authenticated user.

Endpoint: POST /api/apiKeys

Headers:

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

Request Body:

Parameters:

  • name (string, required): Human-readable name for the key
  • type (string, required): Key type ("ai-medical-note" OR "t2yd")
  • status (string, required): Key status ("active", "paused", "expired")

Response:

Get All User API Keys

Retrieves all API keys belonging to the authenticated user.

Endpoint: GET /api/apiKeys/

Headers:

Authorization: Bearer <your_jwt_token>

Response:

Get API Key by ID

Retrieves a specific API key by its ID.

Endpoint: GET /api/apiKeys/{id}

Headers:

Authorization: Bearer <your_jwt_token>

Path Parameters:

  • id (integer, required): The API key ID

Response:

Error Response (404):

{
  "error": "API Key not found"
}

Update API Key

Updates an existing API key's name and type.

Endpoint: PUT /api/apiKeys/{id}

Headers:

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

Path Parameters:

  • id (integer, required): The API key ID

Request Body:

{
  "name": "Updated Production Key"
}

Response:

Delete API Key

Permanently deletes an API key.

Endpoint: DELETE /api/apiKeys/{id}

Headers:

Authorization: Bearer <your_jwt_token>

Path Parameters:

  • id (integer, required): The API key ID

Response:

Pause API Key

Temporarily disables an API key by setting its status to "paused".

Endpoint: PATCH /api/apiKeys/{id}/pause

Headers:

Authorization: Bearer <your_jwt_token>

Path Parameters:

  • id (integer, required): The API key ID

Request:

Response:

Resume API Key

Reactivates a paused API key by setting its status to "active".

Endpoint: PATCH /api/apiKeys/{id}/resume

Headers:

Authorization: Bearer <your_jwt_token>

Path Parameters:

  • id (integer, required): The API key ID

Request:

Response:

Set Default API Key

Sets an API key as the default key for the user.

Endpoint: PATCH /api/apiKeys/setDefault

Headers:

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

Request Body:

Parameters:

  • id (integer, required): ID of the key to set as default
  • old_id (integer, optional): ID of the previous default key (will be unset)

Response:

Remove Default API Key

Removes the default status from an API key.

Endpoint: PATCH /api/apiKeys/removeDefault

Headers:

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

Request Body:

Parameters:

  • id (integer, required): ID of the key to remove default status from

Response:

Get User Keys by User ID

Retrieves API keys for a specific user ID.

Endpoint: GET /api/apiKeys/userKeys/{user_id}

Headers:

Authorization: Bearer <your_jwt_token>

Path Parameters:

  • user_id (integer, required): The user ID

Response:

API Key Object

{
  "id": 1,
  "key": "nux_live_1234567890abcdef",
  "name": "Production API Key",
  "type": "live",
  "status": "active",
  "is_default": true,
  "created_at": "2024-01-15T10:30:00Z",
  "expiry_at": "2025-01-15T10:30:00Z",
  "user_id": 123
}

Field Descriptions:

  • id: Unique identifier for the API key
  • key: The actual API key string used for authentication
  • name: Human-readable name for identification
  • type: Key type (e.g., "live", "test")
  • status: Current status ("active", "paused", "expired")
  • is_default: Whether this is the user's default key
  • created_at: When the key was created (ISO 8601)
  • expiry_at: When the key expires (ISO 8601, null for no expiry)
  • user_id: ID of the user who owns this key

Key Statuses

  • active: Key is operational and can be used for API calls
  • paused: Key is temporarily disabled, can be resumed
  • expired: Key has passed its expiry date and cannot be used

Key Types

  • live: Production keys for live transcription services
  • test: Development/testing keys with potential limitations

Using API Keys for Transcription

Once you have an active API key, use it in the x-api-key header for transcription requests:

curl -X POST "https://nuxera.cloud/api/transcribe" \
  -H "x-api-key: nux_live_1234567890abcdef" \
  -H "Content-Type: multipart/form-data" \
  -F "audio=@recording.wav" \
  -F "userId=123" \
  -F "speciality=General Practice"

Error Responses

All endpoints may return these error responses:

400 Bad Request:

{
  "error": "Invalid request data"
}

401 Unauthorized:

{
  "error": "JWT token required"
}

404 Not Found:

{
  "error": "API Key not found"
}

500 Internal Server Error:

{
  "error": "Failed to create API Key"
}

Best Practices

  1. Key Security: Never expose API keys in client-side code or public repositories
  2. Key Rotation: Regularly create new keys and retire old ones
  3. Default Keys: Set a default key for easier development workflow
  4. Monitoring: Keep track of key usage and expiry dates
  5. Access Control: Use different keys for different environments (production, staging, development)
  6. Pause vs Delete: Use pause for temporary disabling, delete only when permanently removing access

Rate Limits

API Keys management endpoints are subject to standard rate limiting:

  • 100 requests per minute per user
  • 1000 requests per hour per user

Integration Benefits

  • Healthcare Standards: Meets healthcare industry interoperability requirements
  • System Compatibility: Compatible with existing healthcare information systems
  • Audit Compliance: Built-in logging and tracking capabilities
  • Data Integrity: Structured format ensures consistent data exchange
  • Future-Proof: Based on established healthcare messaging standards

Support

For API key issues or questions, contact our support team at saleh@nuxera.ai

Example Usage

Best Practices

  1. Key Security: Never expose API keys in client-side code or public repositories
  2. Key Rotation: Regularly create new keys and retire old ones
  3. Default Keys: Set a default key for easier development workflow
  4. Monitoring: Keep track of key usage and expiry dates
  5. Access Control: Use different keys for different environments (production, staging, development)
  6. Pause vs Delete: Use pause for temporary disabling, delete only when permanently removing access

Rate Limits

API Keys management endpoints are subject to standard rate limiting:

  • 100 requests per minute per user
  • 1000 requests per hour per user

Support

For API key issues or questions, contact our support team at saleh@nuxera.ai