Fix Azure Healthcare APIs: Setup, Access & Config Issues

Everything in Azure Health Data Services lives inside a workspace. The workspace is the top-level container, it holds your FHIR service, your DICOM service, your MedTech service, and your de-identification service all in one place. If the workspace isn't set up right, none of the child services will behave correctly.

Go to Azure Portal → Create a resource → Search for "Azure Health Data Services". Click it, then click Create. On the workspace creation blade, pay close attention to these fields:

• Region: Pick a region where Azure Health Data Services is actually available. Not all Azure regions support this service. Check the regional availability page before you click Create, deploying to an unsupported region silently fails or creates a workspace that can't host services.
• Resource group: Put the workspace and all its child services in the same resource group. Mixing resource groups for the workspace versus the FHIR service creates IAM headaches later.
• Workspace name: This becomes part of every service URL. Keep it short, lowercase, and no special characters. Your FHIR endpoint will look like https://[workspace]-[fhir-service].fhir.azurehealthcareapis.com, a long workspace name makes that URL unwieldy.

Once you hit Review + Create, deployment typically takes 2–5 minutes. After it completes, navigate to the workspace resource and verify its status shows Succeeded under Essentials. A status of Creating that doesn't resolve after 15 minutes usually means a region capacity issue, open a support ticket immediately rather than retrying, as duplicate workspace deployments in the same resource group can collide.

After workspace creation, deploy your FHIR service from inside the workspace: Workspace → FHIR Service → Add. Do not try to deploy a FHIR service as a standalone resource and link it manually, that's the Azure API for FHIR model, and it's being retired. In Azure Health Data Services, the FHIR service must be created within the workspace hierarchy.

When it's working you'll see your FHIR service listed under Services in the workspace blade, with a green checkmark and a clickable endpoint URL.

Azure Healthcare APIs use Microsoft Entra ID (formerly Azure Active Directory) for authentication. Every application that calls your FHIR or DICOM endpoint, whether it's a backend service, a web app, or a mobile client, needs a registered app in your tenant.

Go to Microsoft Entra ID → App Registrations → New Registration. Give it a meaningful name like FHIRClientApp. For the redirect URI, choose Web for server-side apps or Single-page application for browser-based SMART on FHIR clients.

After registration, grab the Application (client) ID and Directory (tenant) ID from the Overview page, you'll need both. Then go to Certificates & Secrets → New Client Secret and generate a secret. Copy it immediately; it's only shown once.

Now the part most teams get wrong: setting the correct API permissions. You do NOT add a permission for "Azure Health Data Services" under API permissions in most scenarios. Instead, your app requests a token scoped directly to the FHIR service URL as the resource. The FHIR service itself validates the token audience, there's no separate API permission entry required for service-to-service flows using client credentials.

For user-delegated flows (SMART on FHIR patient/clinician apps), it's different. You'll need to grant your app permission to the FHIR service under API Permissions → Add a permission → APIs my organization uses → search your FHIR service name. Select the user_impersonation scope and have an admin grant consent.

Test your token acquisition with PowerShell to confirm everything is wired up:

$tenantId = "your-tenant-id"
$clientId = "your-client-id"
$clientSecret = "your-client-secret"
$fhirUrl = "https://your-workspace-your-fhirservice.fhir.azurehealthcareapis.com"

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    resource      = $fhirUrl
}

$tokenResponse = Invoke-RestMethod `
    -Method Post `
    -Uri "https://login.microsoftonline.com/$tenantId/oauth2/token" `
    -Body $body

Write-Host "Token acquired: $($tokenResponse.access_token.Substring(0,50))..."

If this returns a token, you're in good shape. If you get AADSTS700016: Application not found, double-check that your client ID matches what's in Entra ID, and confirm you're in the right tenant.

This is where I see the most time wasted. Azure Healthcare APIs use Microsoft Entra role-based access control (RBAC), not the legacy Azure API for FHIR ACL system. And the roles must be assigned at the FHIR service resource level, not at the subscription or resource group level. Assigning FHIR Data Contributor at the resource group level does nothing.

Here are the roles you'll assign most often:

• FHIR Data Reader, read-only access to FHIR data. Good for analytics pipelines and reporting apps.
• FHIR Data Writer, write access without delete. Right for ingestion services.
• FHIR Data Contributor, full read/write/delete. Use this for admin tools and migration scripts.
• FHIR Data Exporter, required specifically for the $export operation.

Navigate to: Azure Portal → Your FHIR Service resource (not the workspace) → Access Control (IAM) → Add → Add role assignment. Select the appropriate role, then on the Members tab, choose User, group, or service principal and search for your app's managed identity or service principal name.

For managed identities (which I prefer over client secrets in production), go to your compute resource, App Service, Azure Function, or Logic App, enable the system-assigned managed identity there, then come back to the FHIR service IAM blade and assign the role to that identity.

# Assign FHIR Data Contributor to a service principal via Azure CLI
az role assignment create \
  --role "FHIR Data Contributor" \
  --assignee "your-service-principal-object-id" \
  --scope "/subscriptions/your-sub-id/resourceGroups/your-rg/providers/Microsoft.HealthcareApis/workspaces/your-workspace/fhirservices/your-fhir-service"

After the assignment, wait at least 10 minutes before testing. Entra ID role propagation is eventually consistent, there's no way to force-flush it. If after 30 minutes you still get a 403, verify the object ID of the principal you assigned the role to exactly matches the identity making the request. Mismatched object IDs are a silent killer here.

For DICOM service access, the equivalent roles are DICOM Data Owner and DICOM Data Reader, same assignment process, just targeting the DICOM service resource instead of the FHIR service.

Building a patient portal or a SMART on FHIR web app? Then you're going to hit a CORS wall. Browsers enforce same-origin policy, and your FHIR service endpoint is on azurehealthcareapis.com, not your app's domain. Without explicit CORS configuration, every request from the browser will be blocked with a preflight failure, and the error in the console will look like a network error rather than a config problem. I know how maddening that is.

Configure CORS directly on the FHIR service: Azure Portal → Your FHIR Service → Settings → CORS.

You'll see fields for:

• Allowed Origins, add your app's exact origin, e.g., https://mypatientportal.example.com. You can use * for development but never in production, it would expose your PHI endpoint to any origin.
• Allowed Headers, at minimum include Authorization, Content-Type, and x-ms-reply-with-async.
• Allowed Methods, include GET, POST, PUT, DELETE, OPTIONS.
• Expose Headers, include x-ms-request-id for debugging.
• Max Age, set to 600 (10 minutes) to reduce preflight overhead.

Save the settings and give the portal 2–3 minutes to apply the change. Then test with a simple fetch call in the browser console:

fetch("https://your-workspace-your-fhir.fhir.azurehealthcareapis.com/metadata", {
  headers: {
    "Authorization": "Bearer YOUR_TOKEN_HERE"
  }
})
.then(r => r.json())
.then(console.log)
.catch(console.error);

If you get back a JSON CapabilityStatement, CORS is working. If you still see a CORS error, open the browser's Network tab and look at the OPTIONS preflight request. Check the response headers, specifically whether Access-Control-Allow-Origin is present and matches your origin exactly. A mismatch in trailing slash or protocol (http vs https) will cause a failure even if the domain looks right.

One more thing: CORS settings in Azure Health Data Services apply at the FHIR service level, not the workspace level. If you deploy multiple FHIR service instances for different apps or environments, you'll need to configure CORS on each one independently.

Once workspace, app registration, RBAC, and CORS are in place, do a full end-to-end validation before pointing any production system at the endpoint. Skipping this step is how teams discover problems at the worst possible moment.

For the FHIR service, run this validation sequence:

# 1. Check capability statement (no data role needed, just valid token)
curl -s -H "Authorization: Bearer $TOKEN" \
  "$FHIR_URL/metadata" | python3 -m json.tool | head -20

# 2. Create a test Patient resource
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Patient","name":[{"family":"TestPatient","given":["Integration"]}]}' \
  "$FHIR_URL/Patient"

# 3. Search for it
curl -s -H "Authorization: Bearer $TOKEN" \
  "$FHIR_URL/Patient?family=TestPatient" | python3 -m json.tool

If step 2 returns a 201 Created with a resource ID, and step 3 returns a Bundle containing that patient, your FHIR service is fully functional. If step 2 returns 403, you're missing the FHIR Data Writer or FHIR Data Contributor role. If it returns 415, your Content-Type header is wrong, it must be application/fhir+json, not plain application/json.

For the DICOM service, the validation endpoint is slightly different. The DICOM service exposes a DICOMweb-compatible API:

DICOM_URL="https://your-workspace-your-dicom.dicom.azurehealthcareapis.com"

# Check service health
curl -s -H "Authorization: Bearer $DICOM_TOKEN" \
  "$DICOM_URL/v1/changefeed"

A successful response is a JSON array (empty if no changes yet) with HTTP 200. A 404 here usually means the DICOM service URL is wrong, double-check the format in the portal under your DICOM service's Overview blade.

For the de-identification service, test that it can process a sample clinical note using the REST API. The service expects plain text and returns anonymized output with PHI entities tagged, redacted, or replaced, depending on your configuration. A quick smoke test confirms the service endpoint is alive and your managed identity has the right permissions before you route real clinical notes through it.