Blue Button 2.0 is an API from the Centres for Medicare & Medicaid Services (CMS) that incorporates data for 53 million beneficiaries. It contains four years of data that reveals information about the health of each individual, including the Medicare plan they are on right through to the primary care and medicines they receive.

It is an initiative in the U.S. to link claims data from Medicare and make this available to the consumers – i.e. the people who the claim was about. The Blue Button 2.0 API uses the HL7® FHIR® standard as the format and OAuth 2.0 standard and SMART as the authorisation mechanism.

Developers can integrate with the Blue Button 2.0 API which will help individual patients and healthcare organisations to access and monitor health information in one place.

How to connect to the Blue Button 2.0 API

Let’s look at how to connect to the Blue Button 2.0 API using the SMART client that we discussed in a previous blog. There are 2 things we need to do:

  • As an app developer, we need to register our app (in this case the SMART client) to Blue Button2.0 (BB2).
  • As a user of the app, we need to register ourselves with BB2 so we can access our own data.

In this blog, we’ll only concern ourselves with registering the app, as there are test logins available. The first thing we need to do is to create a developer account on the BB2 sandbox here.

Once you have an account, you’ll need to register your application. There’s a button on the site and you’ll need to supply the following details:

  • Name of the application – ‘myBBapp’ sounds elegant.
  • Client type – choose ‘confidential’ – this means we can save a secret and it uses the ‘authorisation code’ grant type that SMART uses.
  • Grant type – choose ‘authorisation code’.
  • Redirect URIs – assuming you’re using the SMART client.

You can ignore the other fields then check the agreement to the service agreement and save. Once you’ve done that, you get a number of elements provided, of which you’re going to need a couple in particular:

  • The client id – uniquely identifies the app (not the user of the app) to BB2 – technically the OAuth server in BB2.
  • The secret – because you said that you could keep one when you registered.

Now you’re ready to load these details into the SMART client.

Load the client, click the ‘Edit Server list’ to the upper right and then click ‘Add’ above the list of servers to add a new one.

Fill in the field on the form using the values you entered and received from the BB2 site. Note that the baseUrl (It is mentioned in the developer site).

It doesn’t appear that the actual value of the scope matters, so I just left it at the default.

Make sure you set the ‘Where to open browser’ to ‘Separate tab’. When you login, the SMART client app will open a separate tab to enter your login details rather than using the iframe in the main page. This is because of security restrictions made by Blue Button that prevents the login opening in an iframe – the original tab will remain open and you’ll still see the progress comments there.

Once that’s done, save it and then you can select the server in the list and login. After retrieving the Capability Statement (which contains the authorisation endpoints) you’ll need to click a ‘continue’ button (a browser security measure – it requires human intervention to authorise the opening of the separate tab).

Assuming you’ve entered everything OK, a new tab will open with the BB2 login form in it. At least in Chrome, the tab opens automatically – other browsers may require you to select it. This means that the app was properly authenticated, and it’s time for the user to identify themselves. If this was operating against the real BB2 site (rather than the sandbox) then this would be the person wanting to access their own data. However, here we’ll need a test login – there are a number of them available. From the BB2 developer website.

The first user is BBUser00000, with password PW00000!, and these sample users continue all the way to BBUser29999, with password PW29999!. (Note: the ! at the end of the password is required.) Enter any one of these to continue.

Next, you’ll be presented with a form informing you that the application you are using (the SMART Client) wishes to access your personal data, and is that OK? To proceed you need to ‘Allow’ this. Assuming you do, you should land at the query screen. This means that everything has worked and you can now start issuing queries. If this were a real app, it would now be able to retrieve data and display it to the user in whatever format it wants.

Before you do that, take a look at the ‘Supported Resources’ tab. You’ll note that only a small number of resources is supported – just as it says in the documentation. Try entering a query like ‘Coverage’ – which asks for all coverage resource. You’ll only get a few – just those that apply to the currently connected user. This is an example of the server applying its own business logic – only supplying data that the current user is entitled to.

And a reminder that the query is an FHIR search. If you want a single resource, then you’ll need to use the _id query. For example, the coverage resource has an element ‘beneficiary’ that is a reference to the Patient (in this case the same as the logged in user – it’s a patient facing service remember).

To get the actual patient resource, use the query: Patient?_id= 19990000000001. You’ll get a bundle with just the single Patient resource.

Then you are able to connect the Blue Button 2.0 API which uses the FHIR standard as the format and OAuth 2.0 standard and SMART as the authorisation mechanism.

To learn more about SMART, read my white paper which reviews SMART, and considers how an organisation can support and benefit from this healthcare standard.

Go to White Paper