Skip to content
Last updated

Authentication

All API requests require authentication using an API key and Clinic ID.

API Key Authentication

We will provide an API Key and Clinic Id. All requests need to pass a header x-api-key with the provided value.

Include your API key in every request:

curl https://novamed-feapidev.stackmod.info/api/external/practitioner \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Required Headers

HeaderValueRequired
x-api-keyYour API keyYes
Content-Typeapplication/jsonYes
Acceptapplication/jsonYes

Clinic ID

Most endpoints also require a clinic_id in the request body. This identifies which clinic the operation is for.

{
  "clinic_id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Smith",
  ...
}

Getting Your Credentials

API credentials are provided by the NovaMed team upon partner approval.

  1. Complete the partner onboarding process
  2. Sign the Business Associate Agreement (BAA) if accessing PHI
  3. Receive your API Key and Clinic ID
  4. Store credentials securely

Important: Store your API key securely. Treat it like a password.

Note: API access is limited to Approved Partners only. By using the API, you agree to the API License Terms & Conditions.

Key Management

Storing Keys Securely

Never commit API keys to version control. Use environment variables or secure secret management:

# Good - use environment variables
export NOVAMED_API_KEY="your-key-here"
export NOVAMED_CLINIC_ID="your-clinic-id-here"

curl -H "x-api-key: $NOVAMED_API_KEY" ...
# Python example
import os

api_key = os.environ.get('NOVAMED_API_KEY')
clinic_id = os.environ.get('NOVAMED_CLINIC_ID')

Use Different Keys Per Environment

Use separate API keys for development and production. This allows you to:

  • Test safely without affecting production
  • Revoke development keys without impacting live integrations
  • Track usage per environment

Restrict Key Access

Limit who has access to API keys:

  • Use secret management tools (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Rotate keys when team members leave
  • Monitor key usage for anomalies

Security Best Practices

Use HTTPS Only

Always use HTTPS. The API requires TLS 1.2 or higher. Never send API keys over unencrypted connections.

Environment Security

EnvironmentURLPHI Allowed
Developmenthttps://novamed-feapidev.stackmod.infoNo
Productionhttps://feapi.novamed.careYes (with BAA)

Important: Do not send PHI to the Development environment.

HIPAA & PHI Handling

The NovaMed API handles Protected Health Information (PHI). When building integrations:

  • Encrypt data in transit: Always use HTTPS (required by the API)
  • Encrypt data at rest: Store any PHI securely in your systems
  • Implement access controls: Limit who can access API keys and PHI
  • Audit access: Log API key usage and data access
  • Follow your compliance policies: Ensure your integration meets HIPAA requirements

The API is designed to comply with HIPAA requirements, but you are responsible for ensuring your integration also complies.

Error Responses

401 Unauthorized

The API key is missing or invalid:

{
  "success": false,
  "error": {
    "message": "Unauthorized. This can happen if the access token is invalid, expired or has been revoked"
  }
}

Solutions:

  • Verify the key is in the x-api-key header (lowercase)
  • Check that the key hasn't been revoked
  • Ensure you're using the correct environment

400 Bad Request

The request is invalid:

{
  "success": false,
  "error": {
    "message": "Clinic not found"
  }
}

Solutions:

  • Verify the clinic_id is correct
  • Check all required fields are provided
  • Validate field formats (UUIDs, emails, etc.)

Example Requests

Create a Practitioner

curl -X POST https://novamed-feapidev.stackmod.info/api/external/practitioner \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Johnson",
    "email": "dr.johnson@clinic.com",
    "npi_number": "1234567890",
    "assigned_clinic": "550e8400-e29b-41d4-a716-446655440000"
  }'

Create a Patient

curl -X POST https://novamed-feapidev.stackmod.info/api/external/patient \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "clinic_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@email.com",
    "date_of_birth": "1985-03-15"
  }'

Next Steps

Previous page
Next page