Testing FHIR System Access with Postman

This tutorial walks you through setting up Postman to test FHIR System Access APIs using OAuth 2.0 client credentials flow in the Preview environment. You'll learn to create environments, configure collections, and make authenticated API requests for system-level access to FHIR resources.

Important: This tutorial uses the Preview environment with test data. Do not use these techniques with production environments containing real patient health information.

Prerequisites

• Postman installed
• Request access to a CareConnect tenant in the Preview environment for testing
• Register your application as a System Access App with CareConnect, which will provide:
  • Client ID
  • Client Secret
  • Tenant ID
• Basic understanding of FHIR and OAuth 2.0 concepts

Getting Started

To begin testing, you'll need to request access to a CareConnect Preview tenant and register your application as a System Access App. This registration allows your app to authenticate using client credentials and access FHIR data at the system level without user interaction.

Overview

System Access enables secure access to FHIR resources using OAuth 2.0 client credentials flow. This tutorial covers:

1. Setting up a Postman environment with variables and secrets
2. Creating a collection with OAuth 2.0 client credentials authorization
3. Making five key API requests:
   • CapabilityStatement (No Auth)
   • SMART Configuration (No Auth)
   • Patient Read (Authenticated)
   • Patient Search GET (Authenticated)
   • Patient Search POST (Authenticated)
4. Troubleshooting common issues

Step 1: Create a Postman Environment

Environments in Postman store variables that can be reused across requests, making it easy to switch between different FHIR servers or configurations.

Creating the Environment

1. Open Postman
2. Click the Environments tab in the left sidebar
3. Click Create Environment
4. Name your environment (e.g., "FHIR System Access - Dev")

Adding Environment Variables

Add the following variables to your environment:

Variable Name	Type	Initial Value	Current Value
tenant_id	default	your-tenant-id	your-tenant-id
base_url	default	https://fhirtest.netsmartcloud.com/provider/system-access/v2	https://fhirtest.netsmartcloud.com/provider/system-access/v2
auth_base_url	default	https://fhirtest.netsmartcloud.com/auth	https://fhirtest.netsmartcloud.com/auth
client_id	default	your-client-id	your-client-id
system_scope	default	system/AllergyIntolerance.rs system/CarePlan.rs system/CareTeam.rs system/Condition.rs system/Coverage.rs system/Device.rs system/DiagnosticReport.rs system/DocumentReference.rs system/Encounter.rs system/Goal.rs system/Immunization.rs system/Location.rs system/Medication.rs system/MedicationDispense.rs system/MedicationRequest.rs system/Observation.rs system/Organization.rs system/Patient.rs system/Practitioner.rs system/PractitionerRole.rs system/Procedure.rs system/Provenance.rs system/ServiceRequest.rs system/Specimen.rs	system/AllergyIntolerance.rs system/CarePlan.rs system/CareTeam.rs system/Condition.rs system/Coverage.rs system/Device.rs system/DiagnosticReport.rs system/DocumentReference.rs system/Encounter.rs system/Goal.rs system/Immunization.rs system/Location.rs system/Medication.rs system/MedicationDispense.rs system/MedicationRequest.rs system/Observation.rs system/Organization.rs system/Patient.rs system/Practitioner.rs system/PractitionerRole.rs system/Procedure.rs system/Provenance.rs system/ServiceRequest.rs system/Specimen.rs

Replace your-tenant-id with your actual tenant ID from your CareConnect app registration.

Adding Secrets

For system access applications, add your client secret:

1. In your environment, add a new variable
2. Set Variable Name to client_secret
3. Set Type to secret
4. Enter your client secret from your CareConnect app registration

Save and Select Environment

1. Select Save
2. Select your environment from the dropdown in the top-right corner

Step 2: Create a Collection with OAuth 2.0 Authorization

Creating the Collection

1. Select Collections in the left sidebar
2. Select Create Collection
3. Name it "FHIR System Access"
4. Add a description: "Collection for testing FHIR System Access APIs with client credentials flow"

Adding Collection Variables

Add variables for temporary data generated during the testing workflow:

1. In your collection, select the Variables tab
2. Add the following variables:

Variable Name	Initial Value	Current Value
patient_id

3. Select Save

Configuring OAuth 2.0 Authorization

1. In your collection, select the Authorization tab
2. Set Type to OAuth 2.0
3. Configure the following settings:

Field	Value
Token Name	CareConnect System Access Token
Grant Type	Client Credentials
Access Token URL	{{auth_base_url}}/:tenant_id/oauth2/v1/token
Client ID	{{client_id}}
Client Secret	{{client_secret}}
Scope	{{system_scope}}
Client Authentication	Send as Basic Auth header

Step 3: Create API Requests

Request 1: CapabilityStatement

The CapabilityStatement describes the FHIR server's capabilities.

1. In your collection, select Add request
2. Name: "Get CapabilityStatement"
3. Method: GET
4. URL: {{base_url}}/:tenant_id/metadata
5. Authorization tab: Set Type to No Auth
6. Params tab:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
7. Select Save

Test the request:

• Select Send
• You should receive a CapabilityStatement resource in JSON format

Request 2: SMART Configuration

The SMART configuration provides OAuth endpoints and supported features.

1. Add another request to your collection
2. Name: "Get SMART Configuration"
3. Method: GET
4. URL: {{base_url}}/:tenant_id/.well-known/smart-configuration
5. Authorization tab: Set Type to No Auth
6. Params tab:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
7. Select Save

Test the request:

• Select Send
• Look for token_endpoint in the response
• Update your collection's OAuth 2.0 configuration:
  • Access Token URL: Copy the token_endpoint value

Getting Your Access Token

Before creating authenticated requests, you need to obtain an access token:

1. Go back to your collection's Authorization tab
2. Scroll down and select Get New Access Token
3. Postman will automatically exchange your client credentials for an access token
4. Select Use Token to apply it to your collection

Request 3: Patient Search (GET)

Start with a patient search to find available patients and automatically set a patient ID for subsequent requests.

1. Add a new request: "Patient Search (GET)"
2. Method: GET
3. URL: {{base_url}}/:tenant_id/Patient
4. Authorization tab: Set Type to Inherit auth from parent
5. Params tab:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
   • Query Params: Add query parameters:
     • Key: _count, Value: 5
6. Select Save

Test the request:

• Select Send
• In the response, look for the entry array
• Each patient will have an id field under entry[].resource.id
• Copy a patient ID from the response (e.g., "12345")
• Go to your collection's Variables tab and update the patient_id variable with this value

Request 4: Patient Read

Now read the specific patient using the ID extracted from the search.

1. Add a new request: "Patient Read"
2. Method: GET
3. URL: {{base_url}}/:tenant_id/Patient/:patient_id
4. Authorization tab: Set Type to Inherit auth from parent
5. Params tab:
   • Path Variables:
     • Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
     • Set patient_id to a specific Patient ID or {{patient_id}} to use environment variable
6. Select Save

Patient ID Required

This request requires a valid patient ID. Run the Patient Search request first, then copy a patient ID from the search results and update your patient_id environment variable.

Test the request:

• Ensure patient_id collection variable is set
• Select Send
• You should receive a single Patient resource in JSON format

Request 5: Patient Search (GET) with Parameters

Search for patients using specific query parameters.

1. Add a new request: "Patient Search (GET) with Parameters"
2. Method: GET
3. URL: {{base_url}}/:tenant_id/Patient
4. Authorization tab: Set Type to Inherit auth from parent
5. Params tab: Add query parameters:
   • Key: family, Value: Smith
   • Key: given, Value: John
   • Key: _count, Value: 10
6. Select Save

Test the request:

• Select Send
• You should receive patients matching the search criteria
• Try different search parameters to see how results change

Request 6: Patient Search (POST)

Search for patients using a POST request with form data.

1. Add a new request: "Patient Search (POST)"
2. Method: POST
3. URL: {{base_url}}/:tenant_id/Patient/_search
4. Authorization tab: Set Type to Inherit auth from parent
5. Body tab: Select x-www-form-urlencoded and add:
   • Key: family, Value: Smith
   • Key: given, Value: John
   • Key: _count, Value: 10
6. Select Save

Test the request:

• Select Send
• Compare results with the GET search to verify they return the same data
• Note that search parameters are in the request body, not the URL

Note: Postman automatically sets the Content-Type header to application/x-www-form-urlencoded when you select this body type.

Security Recommendation

For production applications, prefer POST search requests over GET requests when searching with patient identifiers or other sensitive data. GET requests include search parameters in the URL, which may be logged by servers, proxies, or browsers, potentially exposing patient information.

Step 4: Testing Your Requests

Recommended Testing Order

1. Test CapabilityStatement - Verify server connectivity
2. Test SMART Configuration - Confirm OAuth endpoints
3. Obtain access token - Complete the client credentials flow
4. Test Patient Search (GET) - Find available patients
5. Update patient_id variable - Copy a patient ID from search results
6. Test Patient Read - Verify system-level access
7. Test remaining search requests - Try different search methods

Validating Responses

For each request, verify:

• Status code is 200 OK
• Response contains valid FHIR JSON
• Required fields are present
• Data matches expected format

Troubleshooting Common Issues

Authentication Issues

Problem: "Invalid client" error

• Solution: Verify your client_id and client_secret are correct and registered with CareConnect
• Ensure your app is registered for system access, not patient access

Problem: "Invalid scope" error

• Solution: Check supported scopes in SMART configuration
• Try system/Patient.rs or system/AllergyIntolerance.rs for specific resources
• Ensure you're using system/ scopes, not patient/ or user/ scopes

Problem: Token expired

• Solution: Select "Get New Access Token" in your collection's Authorization tab
• System access tokens typically have longer expiration times than patient access tokens

Problem: "HAPI-0333: Access denied by rule: Request is not authorized for this Tenant" error

• Solution: This error can occur due to tenant configuration OR insufficient authorization:
  • Tenant Issues: Verify your tenant_id path variable is set correctly in each request
  • Tenant Issues: Ensure the tenant ID matches your CareConnect app registration
  • Tenant Issues: Check that you're using the correct tenant ID for your environment (Preview vs Production)
  • Authorization Issues: Verify your access token has the required scopes for the resource or operation
  • Authorization Issues: Confirm your app registration includes permissions for the specific FHIR resources and operations
  • Authorization Issues: Check that your requested scopes were actually granted during the authorization process

Request Issues

Problem: 404 Not Found on SMART configuration

• Solution: Verify your base_url environment variable is correct
• Ensure your path variables for tenant_id are properly set
• Check that your tenant ID matches your CareConnect app registration

Problem: 403 Forbidden on Patient requests

• Solution: Verify your access token has appropriate system scope
• Check if you need additional permissions for system-level access

Problem: Empty search results

• Solution: Try broader search criteria
• Check if test data exists on the server
• Verify search parameter names match FHIR specification

Network Issues

Problem: SSL/TLS certificate errors

• Solution: In Postman Settings, turn off "SSL certificate verification" for testing
• Warning: Only disable when testing with the Preview environment

Problem: CORS errors in browser

• Solution: Use Postman desktop app instead of web version
• CORS doesn't apply to Postman desktop requests

Environment Issues

Problem: Variables not resolving (showing {{variable_name}})

• Solution: Ensure environment is selected in top-right dropdown
• Check variable names match exactly (case-sensitive)
• Verify variables have values set

Problem: Secrets not working

• Solution: Ensure secret variables are set in "Current Value" field
• Check that variable type is set to "secret"

Best Practices

Security

• Use environment variables for all sensitive data
• Set client secrets as secret-type variables
• Don't share environments containing real credentials
• Create separate environments for each tenant in the Preview environment:
  • CareConnect Preview - System Tenant A (fhirtest.netsmartcloud.com)
  • CareConnect Preview - System Tenant B (fhirtest.netsmartcloud.com)
• Each app registration is authorized for only one tenant, so maintain separate credentials per tenant
• Prefer POST search over GET search when using sensitive search parameters to avoid exposing patient data in URLs and server logs

Organization

• Group related requests in folders within collections
• Use descriptive names for requests and variables
• Add documentation to requests explaining their purpose
• Include example responses for reference

Testing

• Add tests to requests to validate responses automatically
• Use pre-request scripts to set up dynamic data
• Create test suites that can run multiple requests in sequence
• Request different formats: Use the Accept header to request XML instead of JSON:
  • For JSON (default): Accept: application/fhir+json
  • For XML: Accept: application/fhir+xml
  • Add these in the Headers tab of your requests

Next Steps

Once you've mastered basic System Access, consider exploring:

• Additional System Resources: Create requests for other resources at the system level:
  • {{base_url}}/:tenant_id/Observation (all lab results, vital signs)
  • {{base_url}}/:tenant_id/Condition (all diagnoses)
  • {{base_url}}/:tenant_id/MedicationRequest (all prescriptions)
  • {{base_url}}/:tenant_id/Organization (healthcare organizations)
  • {{base_url}}/:tenant_id/Practitioner (healthcare providers)
• Bulk Data Export: Testing $export operations with system-level bulk data scopes
• Write Operations: Creating and updating FHIR resources (if supported by your CareConnect app registration)
• Advanced Queries: Using complex search parameters and modifiers for system-wide data analysis

Additional Resources

• SMART App Launch Implementation Guide
• FHIR R4 Specification
• US Core Implementation Guide
• Postman OAuth 2.0 Documentation
• FHIR Bulk Data Access Implementation Guide