Developer Group for CMS Blue Button API
Hello Blue Button 2.0 Community,
To improve the privacy and security of Medicare enrollee data, we're implementing user authorization time limits for the Blue Button 2.0 API (BB2.0). We are giving all existing production applications a 6-month window to prepare for this change.
The new authorization time limits take effect on December 4, 2024, 6 months from today. This timeframe should give you ample time to prepare your applications. Based on our research, most apps already have a mechanism in place to reauthorize users if their use case requires it.
What’s changing?
Currently, when a Medicare enrollee authorizes an app to access their Medicare claims data, that access never expires. With this new feature, we’ve implemented time limits for access to an enrollee’s Medicare claims data based on app category.
How do I know my app's access expiration category?
If you already have an app approved with BB2.0, we will email you over the coming weeks to confirm your category. Below are the categories:
Category: 10 hours
One-time use apps (Example: An app that pulls an enrollee’s data once to recommend insurance plans)
These apps do not usually require separate logins or store users’ data over time.
Authorization will be granted for 10 hours without the ability to refresh the token.
If an enrollee uses the app more than once outside the 10 hour window, they must reauthorize for each data pull.
Category: 13 months
Apps that pull data for the enrollee’s use on an ongoing basis (Example: a personal health aggregator app.)
Authorization will be granted for 13 months.
For continued access after 13 months, an app must prompt the user to reauthorize.
Category: Research
Apps that facilitate Institutional Review Board (IRB)-approved clinical research studies
Access to an enrollee’s data will never expire unless revoked by the enrollee or by the BB2.0 team due to app inactivity over a period of time.
Research apps will be reviewed every 2 years to ensure that they are still active.
If a research app is not active at a 2-year check-in, we will contact the app team for confirmation that they still need BB2.0 API access.
If you have a research app, please keep us updated on changes to your contact information and watch for emails from BlueButtonAPI @cms.hhs.gov.
Access to Medicare claims data is on a per-user basis and starts when a user grants access to their data in the authorization process. For example, in an app with 13-month access, if an enrollee grants access on January 1, 2024, the access grant would expire on February 1, 2025.
This new feature also includes an update of the BB2.0 enrollee-facing permission screens. Enrollees will see how long an app can access their data and have an updated user experience on the new authorization screen. Note that due to space constraints, we have removed company logos on this screen.
Updated authorization screen examples for 10 hour, 13 month and research applications:
What happens when access to a user’s data expires?
Once access to an enrollee’s data expires, applications can’t pull any new data for that enrollee. To continue accessing new data for an enrollee, you’ll need to prompt them to go through the authorization process again.
Do I need to change anything user-facing in my app?
If your app is a 13-month app, we recommend you add a reauthorization workflow, if you don’t have one already, to ensure continued data access. Your workflow should guide enrollees through the reauthorization process so they don’t experience a service gap from your application.
Update and test your approved app to accommodate this feature by December 4, 2024, when we will be turning on this feature for all applications. If you do not support the reauthorization flow by the above date, this may result in an inability to pull data from BB2.0 for your users.
What happens to all the EXISTING users who have already granted access to my app?
For 13-month access apps:
We will add an expiration date for users who have already granted access to their data. This expiration date will be 13 months from the date you turn the feature on. Within this 13 month window, you can retrieve refresh tokens to refresh their BB2.0 data. After 13 months, they will need to reauthorize if you want to continue pulling data.
For one-time access apps:
We will remove existing access grants for users of these applications on the date you turn the feature flag on. All users must reauthorize if you want to continue pulling data for these users.
For Research apps:
There will be no change in the user expiration dates for apps in the research category.
What happens to all the NEW users who grant access to my app?
For 13-month access apps:
When users authorize your app to access BB2.0 data, the access grant expiration will be set to 13 months in the future. Within this 13 month window, you can retrieve refresh tokens to refresh their BB2.0 data. After that date, they will need to reauthorize if you want to continue pulling data.
For one-time access apps:
Authorization will last for 10 hours. After the 10 hour window, all users must reauthorize if you want to continue pulling data.
For Research apps:
Users will authorize your application through the BB2.0 authorization flow. You can retrieve refresh tokens to refresh their BB2.0 data indefinitely.
Sandbox
As part of this effort, we are turning the feature on in the Sandbox today, June 4, 2024. We will run a migration script to change all existing Sandbox apps to the 13-month category. All sandbox apps created going forward will also be categorized as 13-month applications. Note that this means one-time/10-hour apps and research apps will have a different experience in sandbox vs. production. We’ve defaulted to the more complex use case (13-month) for sandbox to ensure applications can handle the reauthorization flow if needed.
Additionally, the /expire_authenticated_user endpoint is available for use in Sandbox for testing your reauthorization flow. Documentation for this endpoint can be found on our website here.
Feature Documentation
To read our documentation about this feature, check out the following sections on our website:
Support
If you need help with anything as you’re implementing this feature, please contact us at BlueButtonAPI @cms.hhs.gov or post your questions here in the Google Group. If you feel you are ready to immediately turn this feature on, you can email BlueButtonAPI @cms.hhs.gov.
Best,
-The Blue Button 2.0 API Team
