Testing FHIR Practitioner Access with Postman

This tutorial walks you through setting up Postman to test FHIR Practitioner Access APIs using the SMART App Launch workflow with OAuth 2.0 authorization code flow in the Preview environment. You'll learn to create environments, configure collections, and make authenticated API requests as a practitioner.

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 Practitioner Access App with CareConnect, which will provide:
  • Client ID
  • Client Secret (for confidential apps only)
  • Tenant ID
  • Approved redirect URIs
• Test practitioner credentials - Username and password for a test practitioner in your assigned tenant (provided by CareConnect)
• 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 Practitioner Access App. This registration allows your app to authenticate practitioners and access FHIR data through the OAuth 2.0 flow with practitioner-level permissions.

Overview

SMART App Launch enables secure access to FHIR resources using OAuth 2.0. This tutorial covers:

1. Setting up a Postman environment with variables and secrets
2. Creating a collection with OAuth 2.0 authorization
3. Making five key API requests:
   • CapabilityStatement (No Auth)
   • SMART Configuration (No Auth)
   • Patient Search (Authenticated)
   • Patient Read (Authenticated)
   • Additional Patient Search methods (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 Practitioner 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/patient-access/v2	https://fhirtest.netsmartcloud.com/provider/patient-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
redirect_uri	default	https://oauth.pstmn.io/v1/callback	https://oauth.pstmn.io/v1/callback
practitioner_scope	default	launch openid fhirUser offline_access user/AllergyIntolerance.rs user/CarePlan.rs user/CareTeam.rs user/Condition.rs user/Coverage.rs user/Device.rs user/DiagnosticReport.rs user/DocumentReference.rs user/Encounter.rs user/Goal.rs user/Immunization.rs user/Location.rs user/Medication.rs user/MedicationDispense.rs user/MedicationRequest.rs user/Observation.rs user/Organization.rs user/Patient.rs user/Practitioner.rs user/PractitionerRole.rs user/Procedure.rs user/Provenance.rs user/ServiceRequest.rs user/Specimen.rs	launch openid fhirUser offline_access user/AllergyIntolerance.rs user/CarePlan.rs user/CareTeam.rs user/Condition.rs user/Coverage.rs user/Device.rs user/DiagnosticReport.rs user/DocumentReference.rs user/Encounter.rs user/Goal.rs user/Immunization.rs user/Location.rs user/Medication.rs user/MedicationDispense.rs user/MedicationRequest.rs user/Observation.rs user/Organization.rs user/Patient.rs user/Practitioner.rs user/PractitionerRole.rs user/Procedure.rs user/Provenance.rs user/ServiceRequest.rs user/Specimen.rs

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

Note: The redirect_uri is set to Postman's OAuth helper URL. If your app registration uses a different redirect URI, update this variable accordingly.

Adding Secrets

Confidential App

For confidential 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

Public App

For public applications, no client secret is required. You can skip adding the client_secret variable.

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 Practitioner Access"
4. Add a description: "Collection for testing FHIR Practitioner Access APIs with SMART App Launch"

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:

Confidential App

Field	Value
Token Name	CareConnect Practitioner Access Token
Grant Type	Authorization Code (With PKCE)
Callback URL	{{redirect_uri}}
Auth URL	{{auth_base_url}}/:tenant_id/oauth2/v1/authorize
Access Token URL	{{auth_base_url}}/:tenant_id/oauth2/v1/token
Client ID	{{client_id}}
Client Secret	{{client_secret}}
Code Challenge Method	SHA256
Code Verifier	(auto-generated by Postman)
Scope	{{scope}}
State	(leave empty or set custom value)
Client Authentication	Send as Basic Auth header

Public App

Field	Value
Token Name	CareConnect Practitioner Access Token
Grant Type	Authorization Code (With PKCE)
Callback URL	{{redirect_uri}}
Auth URL	{{auth_base_url}}/:tenant_id/oauth2/v1/authorize
Access Token URL	{{auth_base_url}}/:tenant_id/oauth2/v1/token
Client ID	{{client_id}}
Client Secret	(leave empty)
Code Challenge Method	SHA256
Code Verifier	(auto-generated by Postman)
Scope	{{scope}}
State	(leave empty or set custom value)
Client Authentication	(not applicable - no client secret)

Important: The Callback URL must exactly match a redirect URI registered in your CareConnect app registration. Whether using Postman's OAuth helper (https://oauth.pstmn.io/v1/callback) or a custom URI, it must be pre-registered with your application.

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 authorization_endpoint and token_endpoint in the response
• Update your collection's OAuth 2.0 configuration:
  • Auth URL: Copy the authorization_endpoint value
  • 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. Important: The redirect_uri must be registered in your CareConnect app registration before proceeding
   • Check "Authorize using browser" if using Postman's OAuth helper (https://oauth.pstmn.io/v1/callback)
   • Ensure your chosen redirect URI is pre-registered with your CareConnect application
4. A browser window will open for authorization
5. Log in using your test practitioner credentials (username and password provided by CareConnect)
6. Authorize the application to access FHIR data
7. Postman will capture the authorization code and exchange it for tokens
8. Select Use Token to apply it to your collection

Request 3: Patient Search (GET)

Start with a patient search to find available patients and 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:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
   • Query Params: 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. Params tab:
   • Path Variables: Set tenant_id to your tenant ID or {{tenant_id}} to use environment variable
6. Body tab: Select x-www-form-urlencoded and add:
   • Key: family, Value: Smith
   • Key: given, Value: John
   • Key: _count, Value: 10
7. 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 OAuth 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 patient-specific 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 is correct and registered with CareConnect
• Check if your client requires a client_secret

Problem: "Invalid redirect URI" error

• Solution: The callback URL must be registered in your CareConnect app registration
• Ensure redirect_uri matches exactly what's registered for your client
• If using https://oauth.pstmn.io/v1/callback, this must be added to your app's allowed redirect URIs

Problem: "Invalid scope" error

• Solution: Check supported scopes in SMART configuration
• Try user/Patient.rs or user/AllergyIntolerance.rs for specific resources
• Ensure you include required scopes like launch openid fhirUser

Problem: Token expired

• Solution: Select "Get New Access Token" in your collection's Authorization tab
• CareConnect provides refresh tokens that Postman can use to automatically refresh expired 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 user scope
• Check if you need additional permissions or practitioner context

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 - Tenant A (fhirtest.netsmartcloud.com)
  • CareConnect Preview - 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 Practitioner Access, consider exploring:

• Additional Patient Resources: Create requests for other resources related to patients:
  • {{base_url}}/:tenant_id/Observation?patient={{patient_id}} (lab results, vital signs)
  • {{base_url}}/:tenant_id/Condition?patient={{patient_id}} (diagnoses)
  • {{base_url}}/:tenant_id/MedicationRequest?patient={{patient_id}} (prescriptions)
  • {{base_url}}/:tenant_id/AllergyIntolerance?patient={{patient_id}} (allergies)
• Practitioner Resources: Access practitioner-specific data:
  • {{base_url}}/:tenant_id/Practitioner (practitioner directory)
  • {{base_url}}/:tenant_id/PractitionerRole (practitioner roles and affiliations)
• Bulk Data Export: Testing $export operations with appropriate bulk data scopes
• Write Operations: Creating and updating FHIR resources (if supported by your CareConnect app registration)

Additional Resources

• SMART App Launch Implementation Guide
• FHIR R4 Specification
• US Core Implementation Guide
• Postman OAuth 2.0 Documentation
• HL7 FHIR Patient Access API Implementation Guide