Back to Nuxera

API Keys Management

Last updated: August 4, 2025

API Keys Management

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

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:

{
  "name": "Production API Key",
  "type": "ai-medicial-note",
  "status": "active"
}

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:

{
  "message": "API Key created",
  "key": "a81bc81b-dead-4e5d-abff-90865d1e13b1",
  "id": 99,
  "user_id": 123
}

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:

[
  {
    "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
  },
  {
    "id": 2,
    "key": "nux_test_abcdef1234567890",
    "name": "Development API Key",
    "type": "test",
    "status": "active",
    "is_default": false,
    "created_at": "2024-01-10T09:15:00Z",
    "expiry_at": null,
    "user_id": 123
  }
]

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:

{
  "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
}

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:

{
  "message": "API Key updated"
}

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:

{
  "message": "API Key deleted"
}

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

Response:

{
  "message": "API key 1 paused."
}

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

Response:

{
  "message": "API key 1 resumed."
}

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:

{
  "id": 1,
  "old_id": 2
}

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:

{
  "message": "API key 1 set as default."
}

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:

{
  "id": 1
}

Parameters:

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

Response:

{
  "message": "API key 1 removed as default."
}

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:

[
  {
    "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
  }
]

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

Support

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

Back to Api keys