SMART Health IT Sandbox: How To Launch And Test SMART Apps

Building a healthcare application that connects to EHRs requires extensive testing before you can go live with real patient data. The SMART Health IT Sandbox gives developers a risk-free environment to build, test, and validate SMART on FHIR applications against simulated Electronic Health Records, without needing access to production systems or dealing with compliance concerns during development.

Whether you're launching your first patient-facing app or expanding an existing product to support new EHR workflows, the sandbox lets you simulate real-world scenarios using synthetic patient data. You can test OAuth authorization flows, query FHIR resources, and debug integration issues before they become expensive problems in production. It's an essential tool for any team building SMART on FHIR applications.

This guide walks you through everything you need to get started: registering your app, configuring launch contexts, testing against different EHR scenarios, and troubleshooting common issues. At SoFaaS, we help healthcare innovators move from sandbox testing to production EHR integrations in days, handling the complexity of connecting to Epic, Cerner, and other major systems. But first, you need to validate your app works correctly, and that's exactly what the sandbox is built for.

By the end of this article, you'll know how to launch and test SMART apps confidently, setting yourself up for a smooth transition to live EHR environments.

What the SMART Health IT Sandbox is

The SMART Health IT Sandbox is a publicly accessible testing platform that simulates real Electronic Health Record systems for developers building healthcare applications. You can use it to register your SMART on FHIR apps, test authorization workflows, and query synthetic patient data without needing contracts with Epic, Cerner, or other EHR vendors. The sandbox environment mirrors how production EHR systems behave, letting you validate your integration logic before spending time and money on live system access.

Think of the sandbox as your development and testing laboratory. It provides multiple pre-configured FHIR servers that represent different EHR scenarios, each loaded with synthetic patient populations and clinical data. You get full access to patient demographics, medications, lab results, allergies, and other FHIR resources. The sandbox supports both patient-facing launch contexts (where patients authorize access to their own data) and provider-facing contexts (where clinicians launch your app from within their EHR workflow).

The sandbox lets you fail fast and iterate quickly without risking real patient data or triggering compliance issues during development.

Core components of the sandbox

The platform consists of several interconnected services that work together to simulate a complete EHR environment. At the center sits a FHIR API server that responds to standard FHIR queries and returns synthetic clinical data in the proper format. This server implements SMART on FHIR launch protocols, meaning it handles the same OAuth 2.0 authorization flows you'll encounter in production systems.

You also get access to the SMART App Launcher, a web-based tool that simulates how your application gets launched from an EHR interface. This launcher lets you select specific patient contexts, provider personas, and launch scenarios. You control which patient record your app opens with, what scopes your app requests, and whether your app launches in a patient portal or clinician workflow. The launcher generates the correct authorization parameters and redirects to your app exactly as a real EHR would.

Additional components include:

• Authorization server that issues OAuth tokens and manages consent workflows
• Patient picker interface that simulates patient selection in clinical contexts
• Multiple FHIR server instances representing different EHR versions and configurations
• Pre-loaded test data sets with diverse patient scenarios and clinical conditions

How the sandbox environment works

When you register your application in the smart health it sandbox, you provide basic information like your app's redirect URI and requested FHIR scopes. The system generates client credentials (client ID and optionally a client secret) that your app uses during the OAuth authorization process. These credentials are specific to the sandbox environment, so you'll need new ones when you move to production EHR systems.

Your application initiates a launch by either responding to a launch request from the SMART App Launcher or by starting a standalone launch directly. The sandbox's authorization server verifies your client credentials, presents a consent screen (if applicable), and issues an access token upon successful authorization. Your app then uses this token to make authenticated FHIR API requests against the sandbox server.

The entire workflow happens over standard HTTP/HTTPS connections using OAuth 2.0 authorization code flow. You can test error conditions by intentionally misconfiguring parameters, requesting invalid scopes, or using expired tokens. The sandbox responds with proper error codes and messages that help you understand what went wrong, making it an excellent learning tool even if you're new to SMART on FHIR development.

What you need before you start

Before you launch your first app in the smart health it sandbox, you need to gather several technical components and make key decisions about your application architecture. Having these elements ready saves time and prevents confusion during the OAuth flow. You don't need production-level infrastructure or extensive healthcare credentials, but you do need working development tools and a clear understanding of your app's data requirements.

Set up your development environment

Your application needs a web server that accepts HTTPS connections for the OAuth redirect callback. The sandbox will send authorization codes to your redirect URI, so this endpoint must be accessible from the internet or you'll need to use localhost tunneling tools during development. You can run a local development server on your machine and use services like ngrok to expose it temporarily for testing.

Install a FHIR client library that matches your programming language. Popular options include HAPI FHIR for Java, fhir.js for JavaScript, or fhirclient.py for Python. These libraries handle the complexities of FHIR resource parsing and SMART authorization flows. You'll also need basic HTTP client capabilities for making REST API calls and JSON parsing tools for handling FHIR responses.

Prepare your application details

You need specific information ready when you register your app with the sandbox authorization server. Collect these details before starting:

• Redirect URI: The exact URL where the sandbox sends authorization codes after user consent
• App launch URL: The entry point where your application receives launch context parameters
• Client type: Whether your app is public (client-side JavaScript) or confidential (server-side with secrets)
• Requested FHIR scopes: The specific patient data and permissions your app needs

Your redirect URI must match exactly what you register, including trailing slashes and query parameters, or the OAuth flow will fail.

Identify your FHIR scope requirements

Determine which clinical data resources your application needs before requesting scopes. The sandbox supports standard SMART scopes like patient/Patient.read for demographics, patient/Observation.read for lab results and vital signs, patient/MedicationRequest.read for prescriptions, and patient/Condition.read for diagnoses. Request only the minimum scopes necessary for your application's core functionality, as overly broad scope requests can trigger authorization failures or security reviews in production environments.

Your scope decisions affect both the patient consent experience and your application's data access patterns. Plan which FHIR resources you'll query and map them to appropriate scopes before starting your integration work.

Step 1. Pick your launch workflow

The smart health it sandbox supports two distinct launch workflows that determine how your application receives patient context and authorization. Your choice affects the entire OAuth flow, the parameters your app receives, and how users interact with your application. You need to decide between an EHR launch (where a provider or patient initiates your app from within the EHR) or a standalone launch (where users start your app independently and select their data source).

This decision shapes your application architecture and user experience. Pick the workflow that matches how users will actually interact with your app in production environments.

EHR launch workflow

An EHR launch simulates your app being launched from within an EHR interface. The sandbox's SMART App Launcher acts as the EHR system, passing your application a launch parameter and an iss (issuer) parameter that identifies the FHIR server. Your app receives these parameters, then redirects to the authorization server with them included in the authorization request. The patient context comes pre-selected because the clinician or patient already has a chart or portal session open.

This workflow fits applications that integrate into clinical workflows like decision support tools, specialized charting modules, or patient education resources. You should choose EHR launch if your app needs to know which patient record the user is viewing before authorization completes, or if your app appears in an EHR's app gallery.

Standalone launch workflow

A standalone launch lets your application initiate the authorization process directly without receiving launch parameters from an EHR. Your app sends users to the authorization server, they authenticate and select which patient record to access, then return to your app with an authorization code. You maintain control over the entire user journey from start to finish.

This workflow works best for patient-facing mobile apps, web portals where patients log in independently, or population health tools that aggregate data across multiple patients. Choose standalone launch if users access your app outside EHR sessions or if your app needs to connect to multiple different EHR systems.

Deciding which workflow to test

Select EHR launch if your production deployment involves appearing in Epic's App Orchard, Cerner's app marketplace, or any scenario where clinicians click a button inside their EHR to open your tool. The authorization happens faster because patient context is predetermined.

Choose standalone launch if patients download your mobile app independently, visit your website directly, or need to authorize access to their own records without clinician involvement. This workflow requires your app to handle patient selection and typically involves more user authentication steps.

Your launch workflow choice determines which parameters you handle during OAuth and affects your entire application flow, so test the pattern you'll actually use in production.

Start with the workflow that matches your target deployment environment rather than testing both simultaneously. You can always switch and test the alternative workflow after validating your primary integration.

Step 2. Configure the SMART App Launcher

The smart health it sandbox provides a web-based SMART App Launcher that simulates how EHR systems initiate your application. You access this tool to configure your app's registration details, select patient contexts, and generate the launch requests that trigger your OAuth flow. This configuration step determines exactly what parameters your application receives when it launches, so you need to set these values carefully to match your testing scenarios.

Access and register your application

Navigate to the SMART App Launcher interface and click the "Register New App" button to add your application to the sandbox environment. You'll enter your application name, redirect URI, and launch URL in the registration form. The system generates a client ID that identifies your app during authorization requests. If your app is confidential (server-side), you'll also receive a client secret that you must store securely and include in token exchange requests.

Your redirect URI must match exactly what your application expects, including the protocol (https://), domain, port number, and path. Copy the client ID immediately because you'll reference it throughout your OAuth implementation. The launcher saves your app configuration and displays it in your list of registered applications where you can edit settings or delete test apps later.

Set your launch parameters

Select your registered application from the launcher interface and configure the launch context settings. You pick which patient record your app should open with by selecting from the available synthetic patients. The launcher lets you choose between different FHIR server versions (R2/DSTU2, R4, etc.) to test compatibility across specifications. You can also simulate different user types by selecting provider personas or patient roles depending on your workflow.

Configure the scopes your app requests by checking the appropriate boxes in the launcher interface. Common configurations include:

• patient/Patient.read for basic demographics
• patient/Observation.read for vitals and lab results
• patient/MedicationRequest.read for prescription data
• launch/patient to receive patient context in EHR launches
• openid fhirUser for user identity information

The launcher generates a launch URL with encoded parameters that you can click to initiate your app, or you can copy the launch parameters to trigger programmatically during automated testing.

Click the "Launch" button to send your app the configured parameters and start the authorization workflow. The launcher redirects to your app's launch URL with the iss and launch parameters appended as query strings.

Step 3. Complete OAuth and get tokens

After the smart health it sandbox launches your app with the appropriate parameters, you need to complete the OAuth 2.0 authorization flow to obtain access tokens. This process involves redirecting users to the authorization server, handling their return with an authorization code, and exchanging that code for the tokens your app uses to access FHIR data. You'll implement three distinct steps: constructing the authorization request, exchanging the code, and storing your access token securely.

Construct the authorization request

Your application receives the launch and iss parameters from the launcher and uses them to build an authorization request URL. You combine your client ID, redirect URI, requested scopes, and the launch parameter into a GET request to the authorization endpoint. The authorization URL follows this pattern:

https://launch.smarthealthit.org/v/r4/auth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=launch/patient patient/Patient.read patient/Observation.read&
  state=RANDOM_STRING&
  aud=https://launch.smarthealthit.org/v/r4/fhir&
  launch=LAUNCH_TOKEN

Replace the placeholder values with your actual client ID, redirect URI, and the launch token you received. The state parameter should be a random string you generate and verify when the authorization server redirects back to prevent cross-site request forgery attacks.

Always validate the state parameter matches what you sent when the authorization server returns control to your app, or an attacker could inject malicious authorization codes.

Exchange the code for tokens

When users complete authorization, the sandbox redirects them back to your redirect URI with an authorization code in the query string. Your application extracts this code and makes a POST request to the token endpoint to exchange it for access tokens. Include your client credentials and the authorization code in the request body:

POST https://launch.smarthealthit.org/v/r4/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=YOUR_CLIENT_ID

The sandbox responds with a JSON payload containing your access token, token type, expiration time, and patient context. Parse this response and extract the access_token value you'll use in FHIR API requests.

Store and use your access token

Save the access token in secure storage appropriate for your application architecture. Server-side apps should use encrypted databases or secure key management services, while client-side apps can use browser session storage. Include the token in the Authorization header of every FHIR API request using the Bearer scheme: Authorization: Bearer YOUR_ACCESS_TOKEN.

Step 4. Call FHIR and validate data

With your access token in hand, you can start making authenticated requests to the FHIR API server and retrieving patient data from the smart health it sandbox. This step confirms your OAuth implementation works correctly and your application can parse FHIR resources properly. You'll query specific endpoints, validate the JSON responses match FHIR specifications, and verify the data contains the clinical information you expect.

Make your first FHIR API request

Start by querying the Patient resource to retrieve basic demographic information about the patient context you received during authorization. You include your access token in the Authorization header and make a GET request to the patient-specific endpoint:

GET https://launch.smarthealthit.org/v/r4/fhir/Patient/PATIENT_ID
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/fhir+json

Replace PATIENT_ID with the patient identifier from your token response. The sandbox returns a JSON object containing the patient's name, birthdate, gender, and address fields formatted according to FHIR R4 specifications. Your application parses this response and extracts the specific fields you need for display or processing.

Validate resource responses

Check that each response includes the required FHIR elements like resourceType, id, and resource-specific mandatory fields. Patient resources must contain at least one identifier and name element. Observation resources need status, code, and either a value or data absent reason. Your validation logic should verify data types match the specification (dates as strings, quantities with units, coded values with system and code).

Proper response validation catches integration issues early before bad data corrupts your application logic or causes runtime errors in production.

Common FHIR queries to test

Query multiple resource types to confirm your scope permissions work correctly and your parser handles different data structures:

GET /Patient/{id}                        // Demographics
GET /Observation?patient={id}            // Labs and vitals
GET /MedicationRequest?patient={id}      // Prescriptions
GET /Condition?patient={id}              // Diagnoses
GET /AllergyIntolerance?patient={id}     // Allergies

Each endpoint returns a Bundle resource containing zero or more matching entries. You iterate through the entry array and process each resource individually, checking for valid FHIR structure and extracting the clinical data points your application displays to users.

Troubleshooting and debugging checklist

When testing your app in the smart health it sandbox, you'll encounter errors that help you identify integration problems before they affect production systems. Most issues fall into predictable categories related to OAuth configuration, token handling, or FHIR query syntax. You can resolve the majority of problems by working through a systematic debugging checklist that verifies each component of your integration separately.

OAuth authorization failures

Check your redirect URI configuration first if authorization fails or users don't return to your app after granting consent. The sandbox requires an exact match between the redirect URI you registered and the one you include in authorization requests. Even trailing slashes, different ports, or protocol mismatches (http vs https) cause failures. You should also verify your client ID matches what the sandbox generated during registration and that your scope requests don't include invalid or unsupported values.

Common authorization issues to verify:

• State parameter mismatch between request and callback
• Missing required parameters like aud or launch in EHR launches
• Incorrect authorization endpoint URL for your selected FHIR version
• Client secret included in public app requests or missing from confidential app requests

Always test your OAuth flow with browser developer tools open to capture redirect URLs and spot parameter mismatches before they become difficult to diagnose.

FHIR API request errors

API calls fail when you use expired access tokens, make requests to the wrong FHIR server endpoint, or query resources outside your authorized scope. You receive HTTP status codes that indicate the problem type: 401 means invalid or expired token, 403 indicates insufficient scope permissions, and 404 means the resource doesn't exist at that endpoint. Inspect the response body for detailed error messages that explain exactly what went wrong.

Check your request format matches FHIR specifications by validating the resource type in your URL path, confirming you include the Authorization: Bearer header with your token, and verifying any query parameters follow FHIR search syntax. Test individual resource queries before attempting complex search operations.

Token parsing problems

Extract the patient context correctly from your token response by parsing the JSON payload and reading the patient field value. Your application needs this identifier to construct patient-specific FHIR queries. If you don't receive a patient ID in the token response, verify you included launch/patient in your scope requests for EHR launches or check that patient selection completed during standalone authorization.

Wrap up and move forward

You now have everything needed to launch and test SMART on FHIR applications in the smart health it sandbox environment. You've registered your app, configured launch workflows, completed OAuth authorization, and validated FHIR data retrieval. These steps prepare you to build robust healthcare integrations that work correctly before connecting to production EHR systems.

Testing in the sandbox gives you confidence your application handles authorization flows properly and parses FHIR resources correctly. You've eliminated the guesswork from your integration development and identified potential issues in a risk-free environment where mistakes don't affect real patient data or trigger compliance violations.

When you're ready to move beyond sandbox testing and connect to real EHR systems like Epic, Cerner, or Allscripts, launch your SMART on FHIR app in a couple of steps with SoFaaS. Our managed platform handles the complexity of production integrations, compliance requirements, and multi-EHR connectivity so you focus on building features your users actually need. You'll go from sandbox to production deployment in days instead of months.