Skip to main content

Introduction to InterSystems FHIR Server

InterSystems® FHIR® Server is a reliable, secure, low maintenance solution that your healthcare application can use to store and retrieve FHIR® data, allowing you to leverage powerful FHIR technology from InterSystems without worrying about setting up its infrastructure.

Follow the easy steps in this introduction to get up and running.

Once you have created a FHIR Server deployment, you can use the Guided Tour to learn how to use RESTful API requests to store and retrieve FHIR data with little to no prior experience.

Before creating an application that uses FHIR Server, you need to choose an Authentication and Authorization strategy, using API keys or OAuth 2.0. Then you will need to Set Up Access Controls.

For information on the day-to-day management of FHIR Server, see InterSystems FHIR Server Reference Information.

To take a deep dive into the FHIR support provided by FHIR Server without needing to examine its Capability Statement, see Supported Interactions and Operations.

To learn how a development team can work together using FHIR Server, see Tenants PageOpens in a new tab.

If you encounter any difficulties while using FHIR Server, see InterSystems FHIR Server Known Issues.

Log in to the Cloud Services Portal

The InterSystems Cloud Services Portal allows you to manage FHIR Server and any additional InterSystems cloud services.

If you have an account in the Cloud Services PortalOpens in a new tab, log in to the portal.

If you do not have an account, sign up for one, as follows:

  1. In your browser, go to the Cloud Services Portal create new account pageOpens in a new tab.

  2. On the Create a New Account page, enter the requested information, and click Create Account.

  3. Type the verification code sent to the email account you provided, and click Submit.

After you create your new account, you are taken to the Cloud Services page.

Sign Up for FHIR Server

You can create a FHIR Server subscription from the Cloud Services page of the Cloud Services Portal.

To subscribe to FHIR Server:

  1. In Cloud Services Portal, on the main menu, click Cloud Services.

    The Cloud Services page shows you any active subscriptions you have to InterSystems cloud services and allows you to sign up for additional services.

  2. On the FHIR Server card, click Subscribe.

  3. On the Subscribe page, read the pricing information and subscription options, and then Subscribe using the method of your choice.

    If you subscribe to FHIR Server with InterSystems, we will bill you directly. If you subscribe with your current cloud provider, billing and subscription management are handled through your account with that cloud provider.

You can also subscribe to FHIR Server and other InterSystems cloud services directly from the AWS MarketplaceOpens in a new tab.

Create a Deployment

Once you have signed up for FHIR Server, you are ready to deploy it in the cloud. If you are a subscriber, you can create multiple deployments, for example, development, test, and live.


If you have just subscribed to FHIR Server in the AWS Marketplace, you may need to wait a few minutes for the subscription to be finalized. You can check to see if this has occurred by checking the Cloud Services page in the Cloud Services Portal and seeing if FHIR Server is listed under Active Subscriptions.

  1. In the Cloud Services Portal, on the main menu, click Deployments.

  2. On the Deployments page, click Create New Deployment.

  3. On the Create InterSystems Deployment page, in the Deployment Options section:

    1. Under InterSystems FHIR Cloud Services, select InterSystems FHIR Server.

    2. Under Deployment Size, select a size.

      A description of the typical use case is listed for each size.

    3. Optionally, select the Highly Available (HA) Configuration to deploy a mirrored backup server automatically to minimize or eliminate downtime to FHIR Server.


      Selecting this option will result in a higher cost to your subscription. This feature cannot be enabled or disabled after the deployment is created.

      This feature is not available with deployments having a size of Nano or Extra Small.

    4. Optionally, select Enable SQL Builder for the ability to create a schema from your FHIR data and query it as you would an SQL database.


      Selecting this option will result in a higher cost to your subscription. This feature cannot be enabled or disabled after the deployment is created.

    5. Click Continue.

  4. In the Cloud Options section:

    1. Under Cloud Provider, select a provider. (“Amazon Web Services” is the only provider currently available.)

    2. Under Region, select a region.

    3. Click Continue.

  5. In the Deployment Name section:

    1. Type a name for your deployment. This cannot be changed once created.

    2. Click Continue.

  6. In the Review section:

    1. Review the summary information.

    2. Click Create.

It takes a few minutes to deploy FHIR Server. When the deployment has completed, the status under the deployment name changes to COMPETE.

Click the card for the deployment to go to the Overview page for your new deployment. This page contains summary information, including your deployment's API Key and OAuth 2.0 endpoints and its Deployment ID. The Deployment ID uniquely identifies your deployment. For more information, see Overview Page.

Other actions are available by clicking the action menu at the top right of the card, such as setting the Service Level for the deployment or deleting the deployment. For more information, see Deployments pageOpens in a new tab.

Guided Tour

Once you have deployed FHIR Server, you can take the following tour to familiarize yourself with FHIR® resources and begin making RESTful FHIR requests.


It is recommended that you perform this tour in a non-live deployment, as it adds test data to your FHIR database.

Find Your FHIR Endpoint

FHIR Server has a unique URL that serves as the base of the RESTful FHIR requests made to the service. This is the FHIR endpoint that you use to work with FHIR data. For example, the request to retrieve a particular patient might be GET https://myEndpoint/Patient/10 while a request that stores an Observation might be POST https://myEndpoint/Observation.

Just navigate to the Overview page to find the FHIR endpoint of your FHIR Server. For example, the FHIR endpoint might look like:


Obtain an API Key

All requests to FHIR Server must be authorized, whether it be with an API key or through OAuth 2.0. For the purposes of this Guided Tour, you will use an API key to authorize the requests.

The Credentials page allows you to add an API key for each user who can access FHIR Server. Create an API key now to use for this tour. For security reasons, this key cannot be accessed again once the dialog is dismissed, so make sure to copy it to a safe place! For more information on creating an API Key, see API Keys.

Shortcut: If you are familiar with FHIR requests and like to use a REST client like Postman, you now have all the information you need to start interacting with FHIR Server. Use the FHIR endpoint as the base URL of your FHIR requests, and authorize those requests by putting your API key in the x-api-key header. However, if you are new to FHIR or RESTful APIs, you can continue with this Guided Tour by using FHIR Server Developer Portal.

Explore the Developer Portal

The Developer Portal found on the API Development page is a great way to familiarize yourself with FHIR resources and make basic API requests that store and retrieve these resources from FHIR Server.

FHIR Server comes preloaded with synthetic healthcare data so that you can get started right away, without having to generate your own test data or de-identify existing data.

Learn About the Patient Resource

The Developer Portal allows you to learn more about individual FHIR R4 resources, which is particularly useful if you are new to FHIR.

  1. From the Select Resource drop-down list, select Patient.

    When you are done with the Guided Tour, you can use this drop-down list to learn about other resources.

  2. Next, expand the POST /Patient section of the Developer Portal.

  3. From here, you can learn more about the structure of a FHIR R4 Patient resource by looking at sample Patients.

    The Example Value text box uses JSON to display the Patient sample that is currently selected in the Examples drop-down list.

  4. Look at the Schemas section of the page to explore the data types, descriptions, and hierarchy of the fields of a valid FHIR R4 Patient resource.

    To see how a Patient is described in the official FHIR specification, see Resource Patient - ContentOpens in a new tab.

Authorize Your FHIR Requests

Like all requests to FHIR Server, the requests made through the Developer Portal must be properly authorized. To authorize your requests made through the Developer Portal:

  1. Near the top of the API Development page, click Authorize.

  2. On the Available Authorizations dialog box, in the Value field, paste the API key you created on the Credentials page.

  3. Click Authorize.

  4. Click Close.

When you are done using the API Development page, click the Authorize button again, and then click Logout.

Add a Patient

You can use the Developer Portal to add Patient resources to FHIR Server without needing to know the syntax of the FHIR request. In FHIR development, adding a resource is accomplished with the createOpens in a new tab interaction. To add a Patient to the service:

  1. Expand the POST /Patient section.

  2. Click Try It Out.

  3. Ensure that patient-example-a.json is selected in the Examples drop-down list. Notice that the value of the Patient’s gender field is male.

  4. Click Execute.

You can review the cURL call that was executed, which gives you an idea of the FHIR request your application would make to add a Patient.

Following the same procedure, add three more Patient resources: patient-example-b.json, patient-example-c.json, and patient-example-d.json. You now have a total of four patients in your database.

Search for Patients

Just as you can use the POST /Patient endpoint to add a Patient to FHIR Server, the Developer Portal allows you to use a GET /Patient endpoint to retrieve Patient resources from the service. Executing a request to this endpoint without specifying parameters will retrieve all of the Patient resources you just added. However, in this Guided Tour, you will retrieve only male patients.

  1. Expand the GET /Patient section.

  2. Click Try It Out.

  3. Scroll through the parameter fields until you find gender, which is a standard search parameter for Patient resources.

  4. Type male.

  5. Scroll down and click Execute.

You can review the cURL call that was executed, which gives you an idea of the FHIR request your application would make to retrieve a Patient using one or more search parameters. Notice that gender=male is added to the end of the endpoint as a query parameter.

The Response Body displays a FHIR bundleOpens in a new tab that contains all of the male Patients in your FHIR Server. You can download this JSON bundle to make it easier to inspect its contents.

Use a REST Client

When using Postman, Advanced REST Client, or any other REST client, be sure to authenticate each request by specifying your API Key as the value of the x-api-key header parameter. For example, your request could include x-api-key: 80nlTZOMyAPIKey. Of course, if FHIR Server is secured with OAuth 2.0, you can use a token to authenticate your requests.

While the API Development page is a great way to start exploring the capabilities of FHIR Server, if you want to try out more complex queries that leverage all of the available search parameters, you need to use a REST client. For a complete list of the standard search parameters, modifiers, and prefixes that are available with FHIR Server, see Search Interaction. These parameters, modifiers, and prefixes can be applied to all searches.

Of course, you can mix these common search parameters with resource-specific parameters when performing a query. As you have seen in this Guided Tour, the API Development page lists all of the resource-specific parameters that are available when searching for resources. These resource-specific parameters are also summarized in the official FHIR specification; for example, you can review the Patient-specific search parametersOpens in a new tab.

Query FHIR Data Using SQL

If you deployed FHIR Server with the SQL Builder option, you can use InterSystems FHIR SQL Builder to create custom SQL schemas from your FHIR data and query the data as you would query an SQL database.

Use FHIR SQL Builder to Create a SQL Projection

FHIR SQL Builder analyzes the data in your FHIR Server, allows you to select which FHIR elements you would like to include in your SQL schema, and creates a projection for the FHIR elements into one or more SQL tables.

To create a SQL projection from your FHIR data:

  1. On the main menu for your deployment, click SQL Builder.

  2. On the InterSystems FHIR SQL Builder page, in the Analyses section, click New.

  3. In the New FHIR Analysis dialog box, for the FHIR Repository, select localhost; for Selectivity Percentage, type 100; and then click Launch Analysis Task.

    When the Percent Complete field reaches 100%, the analysis is done.

  4. In the Transformation Specifications section, click New.

  5. In the New Transformation Specification dialog box, for the Name, type My Transform Spec; for Analysis, select localhost; and then click Create Transformation Specification.

  6. In the Actions column for your transformation specification, click the Edit icon.

  7. In the left pane, click Patient > name > family, and click Add Projection; click Patient > name > given, and click Add Projection; click Patient > gender, and click Add Projection.

    In the Currently Selected Items section, you should see that the transformation will create a schema with a Table named Patient, and three Columns (NameFamily, NameGiven, and Gender).

  8. Click Done to accept this schema.

  9. In the Projections section, click New.

  10. In the New Projection dialog box, for the FHIR Repository, select localhost; for the Transformation Specification, select My Transform Spec; for the Package Name, type MyPackage; and then click Launch Projection.

Your SQL projection is now ready for use!

Use a JDBC Client to Query Your Data

Once you have created a SQL projection from your FHIR data, you can connect to FHIR Server using JDBC or ODBC and query the data with standard SQL queries. But before you can do so, you need to create a firewall rule in FHIR server to enable a connection from the JDBC or ODBC client.

To create a firewall rule:

  1. On the main menu for your deployment, click Firewall.

  2. On the Firewall page, in the External Rules section, slide the Enable External Connections slider to the right.

    You are redirected to the list of deployments while the FHIR Server deployment is updated. This may take a few minutes.

  3. When the status for your deployment changes from UPDATING back to COMPLETE, click the card and navigate back to the Firewall page.

  4. On the Firewall page, in the External Rules section, click Create Rule.

  5. In the Add Firewall Rule dialog box:

    1. In the Port Range box, type 1972.

    2. In the CIDR Block box, type <your external IP address>/32.

    3. Click Add.

To connect your favorite JDBC or ODBC client:

  1. On the main menu for your deployment, click Overview.

  2. In the Overview page, in the xDBC Details section, click the tab that corresponds to the type of client you are using (JDBC or ODBC).

  3. Follow the instructions provided to connect your client.

  4. Once you have connected your client, try running a simple SQL query, such as SELECT * FROM MyPackage.Patient.

Authentication and Authorization

FHIR® requests that are made to FHIR Server can be authenticated by API Key or OAuth 2.0/OpenID Connect using an identity provider (IdP).

API Key Credentials

API keys can be used to authenticate FHIR requests to FHIR Server. Each user is assigned a unique API key that is sent in the header of the request to allow access to the service, as shown in the following example.

curl -i -X POST "https://fhir.<deploymentid>" 
-H "x-api-key:<YOUR-API-KEY>" -H "accept: application/fhir+json" -H "Content-Type: application/fhir+json" 
-i -d "{ \"name\": [ { \"use\": \"official\", \"family\": \"Johnson\", \"given\": [ \"Darcy\" ] } ], 
\"gender\": \"female\", \"birthDate\": \"1970-02-02\", \"resourceType\": \"Patient\" }"

OAuth 2.0/OpenID Connect

FHIR Server OAuth solution is centered around having an authentication server that manages your organization's users and applications. During development, if you want a simplified way to send OAuth tokens to FHIR Server from an application, you can use FHIR Server integrated authentication server. However, an enterprise-grade solution that leverages OAuth and OpenID Connect will most likely use an authentication server that uses an external, third party IdP. In such an implementation, authentication (OpenID Connect) and authorization (OAuth 2.0) for your application is handled by your IdP, not FHIR Server. FHIR Server simply enforces the OAuth tokens obtained from the IdP when responding to FHIR requests from the application.

In many cases, your organization's IdP will already include the users who will be accessing the application that connects to FHIR Server. For example, members of a health insurance company who use applications built for the organization will likely already be users in an IdP. In this scenario, you will simply register your new application with the IdP and give the existing users permissions to access the application. In FHIR Server, you configure your IdP as an authentication server. Then you configure the application to use that authentication server.

When using OAuth 2.0, the user is assigned a temporary token that is sent in the header of the request to allow access to the service, as shown in the following example.

curl -i -X POST "https://fhirauth.<deploymentid>" 
-H "Authorization: Bearer <YOUR-TOKEN>" -H "accept: application/fhir+json" -H "Content-Type: application/fhir+json" 
-i -d "{ \"name\": [ { \"use\": \"official\", \"family\": \"Johnson\", \"given\": [ \"Darcy\" ] } ], 
\"gender\": \"female\", \"birthDate\": \"1970-02-02\", \"resourceType\": \"Patient\" }"

Roles and Responsibilities

Keeping patient data, including Protected Health Information (PHI), safe and secure is of utmost importance in a healthcare application. FHIR Server is designed to use OAuth to protect PHI by inspecting access tokens that accompany FHIR requests from the application. FHIR Server will reject any request that tries to exceed the authorization provided by the scopes of the token.

The following actors are involved in setting up an application to use OAuth 2.0 and OpenID Connect to store and retrieve FHIR resources from FHIR Server. In many cases, especially early in development, one individual might fill more than one role.

Role Responsibilities
Identity Provider Administrator When an external Identify Provider (IdP) is being used for authentication, the IdP Administrator must register the application with the IdP before FHIR Server Administrator can configure the authentication server and application in the Cloud Services Portal. The IdP Administrator is also responsible for adding application users to the IdP so their credentials can be verified in order to issue an access token.
FHIR Server Administrator FHIR Server Administrator is responsible for configuring the authentication server and application in the Cloud Services Portal and providing the configuration details to the Application Developer. If using the integrated authentication server, FHIR Server Administrator also defines the FHIR scopes that the application will be specifying in its request for a token.
Application Developer The Application Developer is responsible for creating the application, such as a SMART on FHIR app, that accesses FHIR Server data. The Application Developer takes the access details of the application’s configuration and modifies values of a SMART app’s authorization methods to obtain access tokens.

When the access token accompanying a request includes a scope to access data in a specific Patient’s compartment, it is the application’s responsibility to set the correct patient context value. For example, if the application user should only be able to view resources pertaining to Patient 1497, then the application must properly set the patient context value to 1497.

Though the Identity Provider Adminstrator or FHIR Server Administrator defines what scopes are possible, it is the Application Developer’s responsibility to ensure that a user’s request includes the proper scopes in order to protect Protected Health Information (PHI).

Set Up Access Controls

Once you have created your FHIR Server deployment and chosen API keys or OAuth 2.0 as an authentication and authorization strategy, you need to set up the access controls needed to govern how users and applications can access the service.

For more information on API keys and OAuth 2.0, see the Authentication and Authorization section of this document.

Create API Keys

API keys can be used to authenticate FHIR requests to FHIR Server. Each new user is assigned a unique API key that is sent in the header of the request to allow access to the service.

You can create and manage API keys on the Credentials page for your deployment.

Set Up OAuth 2.0

To use OAuth 2.0, you need to configure an authentication server and one or more associated applications.

The authentication server is used to authenticate users of your service and can be the integrated authentication server or an external authentication server. The integrated authentication server, built on Amazon Cognito, gives you a quick way to get up and running with FHIR Server. An external authentication server is the preferred solution for organizations that have an existing identity provider (often called an IdP) that can be used to manage users and provide authentication.

An application is a means of tying a FHIR-enabled application to the authentication server. If you are using the integrated authentication server, creating an application allows you to define an authentication flow, as well as set up the scopes that will be used to provide the user with the authorization needed to access the required FHIR resources. If you are using an existing IdP, you need to set up the application in the administrative console of your IdP. Configuring the application in the Cloud Services Portal is then a matter of entering the Client ID and Client Secret of your application, as determined by your IdP.

You can configure an authentication server and its associated applications on the OAuth 2.0 page for your deployment.

If you are using the integrated authentication server, you must also create users who will be permitted to log in to the authentication server in order for them to use the application to access FHIR Server. You can create users on the Credentials page for your deployment.

FeedbackOpens in a new tab