API Key Management¶

The KeyManager class handles all operations related to API key creation and management.

Key Manager Class¶

notedx_sdk.api_keys.key_manager.KeyManager ¶

KeyManager(client: NoteDxClient)

Handles API key management operations for the NoteDx API.

This class provides methods for:

Creating and listing API keys
Managing key metadata
Updating key status
Key deletion

Initialize the key manager.

PARAMETER	DESCRIPTION
`client`	The parent NoteDxClient instance TYPE: `NoteDxClient`

Functions¶

list_api_keys ¶

list_api_keys(
    show_full: bool = False,
) -> List[Dict[str, Any]]

List all API keys associated with the account.

GET /user/list-api-keys

PARAMETER	DESCRIPTION
`show_full`	If True, returns unmasked API keys. Default False for security. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`List[Dict[str, Any]]`	List of dicts, each containing:
`List[Dict[str, Any]]`	key: API key value (masked unless show_full=True)
`List[Dict[str, Any]]`	type: Key type ('sandbox' or 'live')
`List[Dict[str, Any]]`	status: Current status ('active' or 'inactive')
`List[Dict[str, Any]]`	created_at: Creation timestamp (ISO format)
`List[Dict[str, Any]]`	last_used: Last usage timestamp (ISO format)
`List[Dict[str, Any]]`	metadata: Key metadata (only for live keys)

RAISES	DESCRIPTION
`AuthenticationError`	If authentication fails or missing user ID
`AuthorizationError`	If not authorized to list keys
`NetworkError`	If connection issues occur

Note

Keys are sorted with sandbox first, then live keys
Masked keys show only last 4 characters
Metadata is only present for live keys

create_api_key ¶

create_api_key(
    key_type: Literal["sandbox", "live"],
    metadata: Optional[Dict[str, str]] = None,
) -> Dict[str, Any]

Create a new API key.

POST /user/create-api-key

PARAMETER	DESCRIPTION
`key_type`	Type of key to create ('sandbox' or 'live') TYPE: `Literal['sandbox', 'live']`
`metadata`	Optional metadata for live keys Must be dict of string key-value pairs Keys <= 50 chars, values <= 200 chars Cannot contain sensitive keywords TYPE: `Optional[Dict[str, str]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing:
`Dict[str, Any]`	api_key: The full API key value
`Dict[str, Any]`	key_type: Type of key created
`Dict[str, Any]`	metadata: Provided metadata (live keys only)

RAISES	DESCRIPTION
`AuthenticationError`	If authentication fails or missing user ID
`AuthorizationError`	If not authorized to create keys
`BadRequestError`	If invalid JSON format in request
`ValidationError`	If key_type or metadata is invalid
`PaymentRequiredError`	If account has payment issues
`NetworkError`	If connection issues occur

Note

Only one sandbox key allowed per account, unlimited requests with it. Does not use AI, for testing only.
Metadata only supported for live keys
Cannot create live keys if account is cancelled
First live key activates the account

update_metadata ¶

update_metadata(
    api_key: str, metadata: Dict[str, str]
) -> Dict[str, Any]

Update metadata for a live API key.

POST /user/update-api-key-metadata

PARAMETER	DESCRIPTION
`api_key`	The API key to update TYPE: `str`
`metadata`	New metadata dictionary Must be dict of string key-value pairs Keys <= 50 chars, values <= 200 chars Cannot contain sensitive keywords TYPE: `Dict[str, str]`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing:
`Dict[str, Any]`	message: "API key metadata updated successfully"
`Dict[str, Any]`	api_key: Updated key identifier

RAISES	DESCRIPTION
`AuthenticationError`	If authentication fails or missing user ID
`AuthorizationError`	If not authorized to modify key
`BadRequestError`	If invalid JSON format in request
`ValidationError`	If metadata format is invalid
`NotFoundError`	If API key not found
`NetworkError`	If connection issues occur

Note

Only works with live keys
Completely replaces existing metadata
Sensitive keywords not allowed in metadata

update_status ¶

update_status(
    api_key: str, status: Literal["active", "inactive"]
) -> Dict[str, Any]

Update API key status.

POST /user/api-keys/{api_key}/status

PARAMETER	DESCRIPTION
`api_key`	The API key to update TYPE: `str`
`status`	New status ('active' or 'inactive') TYPE: `Literal['active', 'inactive']`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing:
`Dict[str, Any]`	message: "API key status updated successfully"
`Dict[str, Any]`	api_key: Updated key identifier
`Dict[str, Any]`	status: New status value

RAISES	DESCRIPTION
`AuthenticationError`	If authentication fails or missing user ID
`AuthorizationError`	If not authorized to modify key
`BadRequestError`	If invalid JSON format in request
`ValidationError`	If status value is invalid
`NotFoundError`	If API key not found
`NetworkError`	If connection issues occur

Note

Deactivated keys will stop working immediately
Status change is permanent until changed again

delete_api_key ¶

delete_api_key(api_key: str) -> Dict[str, Any]

Delete an API key.

POST /user/delete-api-key

PARAMETER	DESCRIPTION
`api_key`	The API key to delete TYPE: `str`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict containing:
`Dict[str, Any]`	message: "API key deleted successfully"
`Dict[str, Any]`	api_key: Deleted key identifier

RAISES	DESCRIPTION
`AuthenticationError`	If authentication fails or missing user ID
`AuthorizationError`	If not authorized to delete key
`BadRequestError`	If invalid JSON format in request
`NotFoundError`	If API key not found
`NetworkError`	If connection issues occur

Note

Action cannot be undone
Key stops working immediately
Last live key deletion sets account to inactive
Deleted keys remain visible in listings (inactive)

Authentication¶

Note

All API key management operations require Firebase authentication (email/password). API key authentication is not supported for these endpoints.

Key Types¶

The SDK supports two types of API keys:

sandbox: For testing and development
Limited rate limits
No billing
One per account
live: For production use
Higher rate limits
Production billing
Multiple keys allowed

Usage Examples¶

List API Keys¶

# Initialize with Firebase auth
client = NoteDxClient(
    email="user@example.com",
    password="your-password"
)

# List all keys (masked by default)
keys = client.keys.list_api_keys()
for key in keys:
    print(f"Key: {key['key']}")
    print(f"Type: {key['type']}")
    print(f"Status: {key['status']}")

# List with full (unmasked) keys
full_keys = client.keys.list_api_keys(show_full=True)

Create API Keys¶

# Create sandbox key
sandbox = client.keys.create_api_key(key_type="sandbox")
print(f"Sandbox key: {sandbox['api_key']}")

# Create live key with metadata
live = client.keys.create_api_key(
    key_type="live",
    metadata={
        "environment": "production",
        "department": "radiology",
        "purpose": "note-generation"
    }
)
print(f"Live key: {live['api_key']}")

Manage API Keys¶

# Update metadata
client.keys.update_metadata(
    api_key="live_abc123",
    metadata={"environment": "staging"}
)

# Update status (activate/deactivate)
client.keys.update_status(
    api_key="live_abc123",
    status="inactive"
)

# Delete key
client.keys.delete_api_key("live_abc123")

Error Handling¶

from notedx_sdk.exceptions import (
    AuthenticationError,
    AuthorizationError,
    ValidationError
)

try:
    result = client.keys.create_api_key(
        key_type="invalid-type"
    )
except AuthenticationError:
    print("Firebase authentication required")
except AuthorizationError:
    print("Not authorized to manage keys")
except ValidationError as e:
    print(f"Invalid parameters: {e}")

REST API Equivalent¶

# List API keys
curl "https://api.notedx.io/v1/user/list-api-keys" \
     -H "Authorization: Bearer your-firebase-token"

# Create API key
curl -X POST "https://api.notedx.io/v1/user/create-api-key" \
     -H "Authorization: Bearer your-firebase-token" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "live",
       "metadata": {
         "environment": "production"
       }
     }'

# Update metadata
curl -X POST "https://api.notedx.io/v1/user/update-api-key-metadata" \
     -H "Authorization: Bearer your-firebase-token" \
     -H "Content-Type: application/json" \
     -d '{
       "apiKey": "live_abc123",
       "metadata": {
         "environment": "staging"
       }
     }'

# Update status
curl -X POST "https://api.notedx.io/v1/user/api-keys/live_abc123/status" \
     -H "Authorization: Bearer your-firebase-token" \
     -H "Content-Type: application/json" \
     -d '{
       "status": "inactive"
     }'

# Delete key
curl -X POST "https://api.notedx.io/v1/user/delete-api-key" \
     -H "Authorization: Bearer your-firebase-token" \
     -H "Content-Type: application/json" \
     -d '{
       "apiKey": "live_abc123"
     }'