Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
128 lines (86 sloc) 7.47 KB
title description services ms.service ms.subservice ms.topic ms.reviewer author
Postman FHIR server in Azure - Azure API for FHIR
In this tutorial, we will walk through the steps needed to use Postman to access an FHIR server. Postman is helpful for debugging applications that access APIs.

Access Azure API for FHIR with Postman

A client application would access an FHIR API through a REST API. You may also want to interact directly with the FHIR server as you build applications, for example, for debugging purposes. In this tutorial, we will walk through the steps needed to use Postman to access an FHIR server. Postman is a tool often used for debugging when building applications that access APIs.


FHIR server and authentication details

In order to use Postman, the following details are needed:

  • Your FHIR server URL, for example, or
  • The identity provider Authority for your FHIR server, for example,{TENANT-ID}
  • The configured audience. For Azure API for FHIR this is and for the open source FHIR server for Azure, it would be set in the Azure AD resource application registration.
  • The client_id (or application ID) of the client application you will be using to access the FHIR service.
  • The client_secret (or application secret) of the client application.

Finally, you should check that is a registered reply URL for your client application.

Connect to FHIR server

Using Postman, do a GET request to https://fhir-server-url/metadata:

Postman Metadata Capability Statement

In this example, the FHIR server URL is and the capability statement of the server is available at That endpoint should be accessible without authentication.

If you attempt to access restricted resources, you should get an "Authentication failed" response:

Authentication Failed

Obtaining an access token

To obtain a valid access token, select "Authorization" and pick TYPE "OAuth 2.0":

Set OAuth 2.0

Hit "Get New Access Token" and a dialog appears:

Request New Access Token

You will need to some details:

Field Example Value Comment
Token Name MYTOKEN A name you choose
Grant Type Authorization Code
Callback URL
Auth URL{TENANT-ID}/oauth2/authorize?resource=<audience> audience is for Azure API for FHIR and for OSS FHIR server
Access Token URL{TENANT ID}/oauth2/token
Client Secret XXXXXXXX Secret client key
State 1234
Client Authentication Send client credentials in body

Hit "Request Token" and you will be guided through the Azure Active Directory Authentication flow and a token will be returned to Postman. If you run into problems open the Postman Console (from the "View->Show Postman Console" menu item).

Scroll down on the returned token screen and hit "Use Token":

Use Token

The token should now be populated in the "Access Token" field and you can select tokens from "Available Tokens". If you "Send" again to repeat the Patient resource search, you should get a Status 200 OK:

200 OK

In this case, there are no patients in the database and the search is empty.

If you inspect the access token with a tool like, you should see content like:

  "aud": "",
  "iss": "{TENANT-ID}/",
  "iat": 1545343803,
  "nbf": 1545343803,
  "exp": 1545347703,
  "acr": "1",
  "aio": "AUQAu/8JXXXXXXXXXdQxcxn1eis459j70Kf9DwcUjlKY3I2G/9aOnSbw==",
  "amr": [
  "appid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "oid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "appidacr": "1",

  ...// Truncated

In troubleshooting situations, validating that you have the correct audience (aud claim) is a good place to start. The managed Azure API for FHIR uses identity object IDs to restrict access to the service. Make sure that oid claim of the token contains an object ID from the list of allowed object IDs.

It is also possible to get a token for the Azure API for FHIR using the Azure CLI.

Inserting a patient

Now that you have a valid access token. You can insert a new patient. Switch to method "POST" and add the following JSON document in the body of the request:


Hit "Send" and you should see that the patient is successfully created:

Patient Created

If you repeat the patient search, you should now see the patient record:

Patient Created

Next steps

In this tutorial, you've accessed an FHIR API using postman. Read about the supported API features in our supported features section.

[!div class="nextstepaction"] Supported features

You can’t perform that action at this time.