{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication","description":"API documentation for integrating with NovaMed - healthcare partner integration platform","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API requests require authentication using an API key and Clinic ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-key-authentication","__idx":1},"children":["API Key Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We will provide an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API Key"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clinic Id"]},". All requests need to pass a header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," with the provided value."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include your API key in every request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://novamed-feapidev.nimbushealthcaretest.com/api/external/practitioner \\\n  -H \"x-api-key: your-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-headers","__idx":2},"children":["Required Headers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Accept"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"clinic-id","__idx":3},"children":["Clinic ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most endpoints also require a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clinic_id"]}," in the request body. This identifies which clinic the operation is for."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"clinic_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Smith\",\n  ...\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-your-credentials","__idx":4},"children":["Getting Your Credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API credentials are provided by the NovaMed team upon partner approval."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete the partner onboarding process"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sign the Business Associate Agreement (BAA) if accessing PHI"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receive your API Key and Clinic ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store credentials securely"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important"]},": Store your API key securely. Treat it like a password."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": API access is limited to Approved Partners only. By using the API, you agree to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-terms"},"children":["API License Terms & Conditions"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-management","__idx":5},"children":["Key Management"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"storing-keys-securely","__idx":6},"children":["Storing Keys Securely"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never commit API keys to version control. Use environment variables or secure secret management:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Good - use environment variables\nexport NOVAMED_API_KEY=\"your-key-here\"\nexport NOVAMED_CLINIC_ID=\"your-clinic-id-here\"\n\ncurl -H \"x-api-key: $NOVAMED_API_KEY\" ...\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"# Python example\nimport os\n\napi_key = os.environ.get('NOVAMED_API_KEY')\nclinic_id = os.environ.get('NOVAMED_CLINIC_ID')\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-different-keys-per-environment","__idx":7},"children":["Use Different Keys Per Environment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use separate API keys for development and production. This allows you to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test safely without affecting production"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke development keys without impacting live integrations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track usage per environment"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"restrict-key-access","__idx":8},"children":["Restrict Key Access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Limit who has access to API keys:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use secret management tools (AWS Secrets Manager, HashiCorp Vault, etc.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rotate keys when team members leave"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Monitor key usage for anomalies"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-best-practices","__idx":9},"children":["Security Best Practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-https-only","__idx":10},"children":["Use HTTPS Only"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always use HTTPS. The API requires TLS 1.2 or higher. Never send API keys over unencrypted connections."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"environment-security","__idx":11},"children":["Environment Security"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"URL"},"children":["URL"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"PHI Allowed"},"children":["PHI Allowed"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Development"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://novamed-feapidev.nimbushealthcaretest.com"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Production"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://feapi.novamed.care"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes (with BAA)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important"]},": Do not send PHI to the Development environment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hipaa--phi-handling","__idx":12},"children":["HIPAA & PHI Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The NovaMed API handles Protected Health Information (PHI). When building integrations:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Encrypt data in transit"]},": Always use HTTPS (required by the API)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Encrypt data at rest"]},": Store any PHI securely in your systems"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implement access controls"]},": Limit who can access API keys and PHI"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Audit access"]},": Log API key usage and data access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Follow your compliance policies"]},": Ensure your integration meets HIPAA requirements"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API is designed to comply with HIPAA requirements, but you are responsible for ensuring your integration also complies."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-responses","__idx":13},"children":["Error Responses"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-unauthorized","__idx":14},"children":["401 Unauthorized"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API key is missing or invalid:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Unauthorized. This can happen if the access token is invalid, expired or has been revoked\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solutions"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the key is in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header (lowercase)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that the key hasn't been revoked"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure you're using the correct environment"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"400-bad-request","__idx":15},"children":["400 Bad Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request is invalid:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Clinic not found\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solutions"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clinic_id"]}," is correct"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check all required fields are provided"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate field formats (UUIDs, emails, etc.)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-requests","__idx":16},"children":["Example Requests"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-practitioner","__idx":17},"children":["Create a Practitioner"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://novamed-feapidev.nimbushealthcaretest.com/api/external/practitioner \\\n  -H \"x-api-key: your-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json\" \\\n  -d '{\n    \"first_name\": \"Sarah\",\n    \"last_name\": \"Johnson\",\n    \"email\": \"dr.johnson@clinic.com\",\n    \"npi_number\": \"1234567890\",\n    \"assigned_clinic\": \"550e8400-e29b-41d4-a716-446655440000\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-patient","__idx":18},"children":["Create a Patient"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://novamed-feapidev.nimbushealthcaretest.com/api/external/patient \\\n  -H \"x-api-key: your-api-key-here\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json\" \\\n  -d '{\n    \"clinic_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"first_name\": \"John\",\n    \"last_name\": \"Smith\",\n    \"email\": \"john.smith@email.com\",\n    \"date_of_birth\": \"1985-03-15\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":19},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/quickstart"},"children":["Make your first request"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/errors-idempotency"},"children":["Learn about error handling"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-reference"},"children":["Read the API reference"]}]}]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"API Key Authentication","id":"api-key-authentication","depth":2},{"value":"Required Headers","id":"required-headers","depth":3},{"value":"Clinic ID","id":"clinic-id","depth":3},{"value":"Getting Your Credentials","id":"getting-your-credentials","depth":2},{"value":"Key Management","id":"key-management","depth":2},{"value":"Storing Keys Securely","id":"storing-keys-securely","depth":3},{"value":"Use Different Keys Per Environment","id":"use-different-keys-per-environment","depth":3},{"value":"Restrict Key Access","id":"restrict-key-access","depth":3},{"value":"Security Best Practices","id":"security-best-practices","depth":2},{"value":"Use HTTPS Only","id":"use-https-only","depth":3},{"value":"Environment Security","id":"environment-security","depth":3},{"value":"HIPAA & PHI Handling","id":"hipaa--phi-handling","depth":2},{"value":"Error Responses","id":"error-responses","depth":2},{"value":"401 Unauthorized","id":"401-unauthorized","depth":3},{"value":"400 Bad Request","id":"400-bad-request","depth":3},{"value":"Example Requests","id":"example-requests","depth":2},{"value":"Create a Practitioner","id":"create-a-practitioner","depth":3},{"value":"Create a Patient","id":"create-a-patient","depth":3},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Authentication","description":"Authenticate API requests with API keys","seo":{"title":"Authentication"}},"lastModified":"2025-12-19T22:59:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}