Smart on FHIR for Patient Access API

General

Blue Cross and Blue Shield of Minnesota offers two APIs so you can build applications for our members.

• The Patient Access API lets Blue Cross members access claims, drug formularies and a set of clinical data. This API is secured by SMART on FHIR. To continue, you’ll need to create a developer account.
• The Provider Directory API lets Blue Cross members access our provider directory. There is no security required to access this API.

Getting Started

The SMART App Launch Framework connects third-party applications to the Patient Access API. it is based on the OAuth 2.0 specification and the OpenID Connect Core 1.0 Standard.

Currently the Blue Cross FHIR authorization server supports the standard OAuth 2.0 and OIDC web application authorization flow. It does not support the Proof Key for Code Exchange (PKCE) authorization flow.

If your application is dependent on a PKCE authorization flow, please reach out to us and we will prioritize it.

After registering your application, you will get a client ID and client secret (keep this secured).

We have provided a link to our well-known endpoint, which details the authorization server's capabilities. Keep in mind our developer sandbox and our production environments each have their own FHIR authorization server.

How it Works

• Using your application, a Blue Cross member will want to authorize and consent to your application as a valid recipient of their highly confidential healthcare information.
• Your application will send a request to the Blue Cross FHIR authorization server asking for authorization.
• The Blue Cross FHIR authorization server will redirect the Blue Cross member to a login page where they will authenticate themselves and consent to allowing your application access to their highly confidential healthcare information.
• After authorization and consent is completed, the Blue Cross FHIR authorization server will redirect back to your application (at the redirect URI you provided during registration of your application). The authorization code will be included in the query parameters.
• Your application will then use the authorization code (and your client secret) to ask for an access token (JWT).
• Once you have the access token you will include it on all FHIR requests made on behalf of the Blue Cross member. The access token will appear in the request header as an authentication bearer token.

The Supported Scopes

The Supported Capabilities

Putting this Together

1. Your application will send a request to the BCBS-MN FHIR authorization server asking for authorization.

       
   GET https://xxxx.bluecrossmn.com/fhir/authorize?response_type=code&client_id=YOUR_CLIENT_ID&scope=launch/patient%20patient/*.read%20offline_access%20fhirUser%20openid&redirect_uri=http://YOUR_HOST:3000/redirect/callback&aud=https://api-xxxx.bluecrossmn.com/fhir&state=dev&nonce=d1bgsv478gr
   

   
   In this example, your application is asking the BCBS FHIR authorization server for several things:

   response_type=code	an authorization code
   redirect_uri	the location where the authorization code should be delivered. This must match a location you specified when registering your application.
   scope=launch/patient	a patient context
   patient/*.read	and the ability to read all the patient's information
   fhirUser%20openid	your application wants to know who is using the application, it may not be the patient

2. The BCBS-MN FHIR authorization server will re-direct the BCBS-MN customer to a login page where they will authenticate themselves and consent to allowing your application access to their highly confidential healthcare information.
    

   https://xxxx.bluecrossmn.com/member/index.html
   

   
   Once here several other pages and redirects may occur, your application should not care.
3. Upon successful completion of the authorization and consent, the BCBS-MN FHIR authorization server will redirect back to your application (at the redirect URI you provided during registration of your application). The authorization code will be included in the query parameters.
    

   http://YOUR_HOST:3000/redirect/callback?code=XFeKf40Xqao9EXTlde5uyWo1H_pQ&state=dev
   

   code	the authorization code you requested

4. Your application will then use the authorization code (and your Client Secret) to ask for an Access Token (JWT).

       
   POST https://xxxx.bluecrossmn.com/fhir/token
   

   Header:

       
   authorization: Basic base64(YOUR_CLIENT_ID: YOUR_CLIENT_SECRET) <basic-auth>
   content-type: application/x-www-form-urlencoded
   

   Data:

       
   code: XFeKf40Xqao9EXTlde5uyWo1H_pQ
   grant_type:
   redirect_url
   
   

   The response will look like this:

       
   {
     "token_type": "Bearer",
     "expires_in": 3600,
     "access_token": "eyJraWQiOiJOc3JibVd0MkZ0bDBHUzQxUWdSNUhsMW1tV2Z6ZzI0RldrMzJPZXQ1c0ZZIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULkY4WlpmNG14d2Jtck5xVHllcTV3X3B0a0xDdH1uMy5va3RhcHJldmlldy5jb20vb2F1dGgyL2F1c2dkcmEycW5JMjZjMGtNMWQ2IiwiYXVkIjoiYXBpOi8vZGVMyOC1IIiwidmFsaWRfY29uc2VudCI6InRydWUifQ.n1IZao3S6GFLv_vYD5oWiFpKida4E7BPkfTPzeFx2GJEKwVMAGUr2US95EZZvwvg21j0YaJjCpA2j2059u1J75qHfsiR6sIdfdFHMMX-ANTrzWe5JW4Gnzs9PqrAk4RDjEvN45TYPx1fvEg2dDAisOh20-fO-tgdmyXOdziq-JH_S66tglPkWi8-SCBGlDouLRzQZIsJG5AzzgTyPuavkYNVhQJ1OqXupQ-pzmXGO7xu8MnHS-Rl2drhuVpgW35WSv_7mARkCsnvUgWqZ_xWX8Hpk_81RsIb0vQBbisJ1hI1-acn6DYniH1r-TPwCIakuwSsRkd4HWzJlIdrjKkojA",
     "scope": "fhirUser offline_access openid launch/patient patient/*.read",
     "refresh_token": "S1i4NPghcmqbvgA-oKUnI6KWOc",
     "id_token": "eyJraWQiOiJOc3JibVd0MkZ0bDBHUzQxUWdSNUhsMW1tV2Z6ZzI0RldrMzJPZXQ1c0ZZIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIwMHVxdjd5NjBMbUFRYXBJYTFkNiIsInZlciI6MSwiaXNzIjoiaHR0cHMRKRfZk21RRHPlm_gYWGZT0nU170kPsmgTZT2UOAnvPbwoCPQdwY2mESKRJQ9DvBvP4Kaxxzt2cNeLVfFNoF7MSEEb6AdDZupT_SURHpY8wzrvpGKPYD99HUbjbIbuBsWF_70orz5zLv_DKbIMie7ND_TJ5dNLqw5QYW3S71W5JSLpBmhBh6kfqo1i6B5lEaGpi6y9BsuD1vAPes2a24acj4S0G_XGnLHBSYSvpXUcRXPaRddwNxYYY2IcJ4tO9zg8JT0VIjDCcKc57TfC0_h0A",
     "patient": "BCBSMN-11328-H"
   }
   
   

   The response contains a lot of information you will want to be aware of.

   token_type	the type of token
   access_token	the token itself
   expires_in	when the token expires
   scope	the scopes your application was granted, these may or may not match the scopes you requested
   refresh_token	in this example your application requested and was granted a refresh token
   id_token	in this example your application requested and was granted an openid token identifying the user using your application
   patient	in this example your application requested a patient context, it is provided by the FHIR ID of the patient

5. Once you have the Access Token you will include it on all FHIR requests made on behalf of the Blue Cross Blue Shield of Minnesota customer. The Access Token will be presented in the request header as an authentication bearer token.

       
   GET https://xxxx.bluecrossmn.com/fhir/Patient
   
   

   Header:

       
   authorization: Bearer {The_Access_Token}
   
   

Users You Can Use to Test

The following two users are set up for testing.