Query Connector

← Back to Documentation

API Documentation

The DIBBs Query Connector API is a RESTful API that allows public health staff to query a wide network of healthcare organizations (HCOs) for patient data.

  • Interactive API documentation is available here.
  • A Postman collection demonstrating use of the API can be found here.

Queried FHIR Resources

Query results are returned as a FHIR Bundle containing the patient's records. Depending on the contents of the query being run, the bundle can include the following resource types:

  • Patient
  • Observation (lab results, plus social determinants of health if enabled for the query)
  • DiagnosticReport
  • Condition
  • Encounter
  • MedicationRequest
  • MedicationStatement
  • Immunization
  • ServiceRequest

Lab, condition, and medication resources are filtered to the value set codes configured in the query. Immunization, social determinants Observation, and ServiceRequest resources are returned when the corresponding medical record sections are enabled for the query. Medication and service request queries may also return related resources (such as Medication, MedicationAdministration, Practitioner, and Specimen) via _include/_revinclude search parameters.

Authentication

The Query Connector API uses OAuth 2.0 Client Credentials flow for authentication. API requests must include a valid access token in the Authorization header.

Quick Start

  1. Get an access token using your client credentials
  2. Include the token in your API requests: Authorization: Bearer YOUR_ACCESS_TOKEN

The specific setup depends on your identity provider:

Keycloak Setup

Before you begin, ensure you have the following:

  • Access to the Keycloak Admin Console
  • Permissions to create clients and assign roles
  • The main Query Connector client already created (e.g., query-connector-client) and configured with the api-user role

1. Create a Service Account Client

  1. Log into your Keycloak Admin Console
  2. Navigate to your realm → Clients → Create client
  3. Configure the client:
    • Client ID: Choose a descriptive name (e.g., my-api-client)
    • Client Protocol: openid-connect
    • Client Authentication: On
    • Authorization: Off
    • Authentication flow: Disable all except "Service accounts roles"
  4. Save the client

2. Get Client Credentials

  1. Go to your client → Credentials tab
  2. Copy the Client Secret (you'll need this to get tokens)

3. Assign the API User Role

  1. Go to your client → Service Account Roles tab
  2. Click Assign role
  3. Search for and select the api-user role on the Query Connector client
  4. Click Assign

4. Get an Access Token

curl -X POST "https://YOUR_KEYCLOAK_URL/realms/YOUR_REALM/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "expires_in": 300,
  "token_type": "Bearer"
}

5. Use the Token

Include the access token in your API requests:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://queryconnector.dev/api/query?fhir_server=SERVER_NAME&id=QUERY_ID"

Microsoft Entra ID Setup

Before you begin, ensure you have the following:

  • Access to the Azure Portal
  • Permissions to create app registrations and manage API permissions
  • The main Query Connector application already registered in Microsoft Entra ID with the api-user app role defined

1. Create an App Registration

  1. Log into the Azure Portal
  2. Navigate to Microsoft Entra ID → App registrations → New registration
  3. Configure the registration:
    • Name: Choose a descriptive name (e.g., QC API Client - Production)
    • Supported account types: "Accounts in this organizational directory only"
  4. Click Register

2. Create Client Secret

  1. Go to your app registration → Certificates & secrets
  2. Click New client secret
  3. Add a description and expiration period
  4. Click Add
  5. Copy the secret value immediately (it won't be shown again)

3. Request API Access

  1. Go to API permissions → Add a permission
  2. Click My APIs
  3. Select the Query Connector application
  4. Choose Application permissions
  5. Select the api-user permission
  6. Click Add permissions
  7. Click Grant admin consent (requires admin privileges)

4. Assign the App Role

Note: This step requires Azure CLI or PowerShell as it cannot be done through the portal.

Using Azure CLI:

# Get the necessary IDs
CLIENT_APP_ID="YOUR_CLIENT_APP_ID"
QC_APP_ID="QUERY_CONNECTOR_APP_ID"

# Get service principal IDs
CLIENT_SP=$(az ad sp show --id $CLIENT_APP_ID --query id -o tsv)
RESOURCE_SP=$(az ad sp show --id $QC_APP_ID --query id -o tsv)

# Get the api-user role ID
APP_ROLE_ID=$(az ad sp show --id $QC_APP_ID --query "appRoles[?value=='api-user'].id" -o tsv)

# Create the role assignment
az rest --method POST \
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$CLIENT_SP/appRoleAssignments" \
  --body "{\"principalId\": \"$CLIENT_SP\", \"resourceId\": \"$RESOURCE_SP\", \"appRoleId\": \"$APP_ROLE_ID\"}"

5. Get an Access Token

curl -X POST "https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=api://QUERY_CONNECTOR_APP_ID/.default" \
  -d "grant_type=client_credentials"

Example response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."
}

6. Use the Token

Include the access token in your API requests:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://queryconnector.dev/api/query?fhir_server=SERVER_NAME&id=QUERY_ID"

Token Management Best Practices

  1. Cache tokens: Tokens are valid until expiration. Cache and reuse them instead of requesting new ones for each API call.

  2. Handle expiration: Check the expires_in value and refresh tokens before they expire.

  3. Secure storage: Store client secrets securely using environment variables or secret management systems.

  4. Error handling: If you receive a 401 Unauthorized error, get a new token and retry the request.

Troubleshooting

401 Unauthorized

  • Token expired: Get a new token
  • Missing role: Verify the api-user role is assigned to your client
  • Wrong audience: For Entra, ensure you're using the correct scope

Invalid Token Errors

  • Malformed token: Ensure you're sending only the token value, not the entire response object
  • Wrong identity provider: Verify you're using the correct token endpoint for your environment

Need Help?