CMS Blue Button

Create a Developer Account

1. Go to the CMS Blue Button Sandbox and sign up with a business email.
2. CMS sends a verification link, confirm it before proceeding.
3. Sign in and you’ll land on the Developer Dashboard.

Register a Sandbox Application

1. From the Developer Dashboard, click Add an Application (or the ADD AN APPLICATION button in the hero).
2. You land on the Register a New Application form.

3. Fill in App Details, Required Info:

• Application Name, your product’s user-facing name. This is what beneficiaries see on the CMS consent screen and on medicare.gov’s “My Connected Apps”.
• Callback URLs / Redirect URIs, one per line. Must start with http:// or https:// and contain no fragments (#) or query strings (?).
• Does your application need to collect beneficiary demographic information?, Yes if you need name, address, date of birth, race, sex. Selecting Yes means the CMS consent screen surfaces a Personal Information toggle the beneficiary can uncheck.

Register every redirect URI you’ll use end-to-end, local dev, staging, and production:

• http://localhost:3000/api/auth/smart/callback
• https://staging.yourdomain.com/api/auth/smart/callback
• https://app.yourdomain.com/api/auth/smart/callback

If you’re on the Medblocks Platform, your backend already exposes /api/auth/smart/callback, just register the hostnames you deploy to, including https://app.medblocks.com/api/auth/smart/callback.

Optional App Information

This section is technically optional for sandbox, but filling it in now is required for production access, and it simulates what real Medicare beneficiaries will see on the consent screen, so it’s worth doing right the first time.

1. Upload a Logo, JPG, JPEG, or PNG, max 100 KB, max 512×512 px. This appears next to your app name on the consent screen and in the beneficiary’s connected-apps list. Use the same logo you publish elsewhere.
2. Application Description, up to 1000 characters. Plain-English description of what your app does with Medicare data. Cover what data you pull, who sees it, and the purpose. Keep it patient-readable, this is the description CMS reviewers will compare to your actual user-facing screens during the production demo.

Organization & Policy Info

Fill in:

• Organization / Company Website URL, your company’s marketing site.
• Privacy Policy URL, a live page covering the CMS-required sections: collection, use, sharing, retention after revocation, dormant-account handling, breach notification, and data handling on company sale. If you’re on the Medblocks Platform, docs/medblocks-privacy-policy.md in the connect-web repo is a starting template.
• Terms of Service URL, leave blank for sandbox; required for production, point it at your hosted ToS.
• Customer Support Email, a monitored inbox. CMS uses this address for sandbox notifications and review correspondence.
• Customer Support Phone Number, optional for sandbox; strongly recommended for production, CMS reviewers may try to call.
• App Development Team Contacts, comma-separated list of 2–4 engineers CMS can reach for technical issues.

Accept the Agreement and Save

1. Tick Yes I have read and agree to the API Terms of Service Agreement, read it; it covers attribution requirements (the “not endorsed by CMS” disclaimer) and prohibited uses (no advertising, no profiling, no sale of data).
2. Click Save Application.

You’re redirected to the application detail page.

Save your Client ID and Client Secret

1. In App Credentials, click Show/Hide Credentials to reveal the Client ID and Client Secret. Copy both into your secret manager immediately, a leaked secret means re-registering the app.
2. Plug the credentials into Medblocks:
   • Go to Settings.
   • Select Connections.
   • Find Medicare and open it.
   • Toggle Use custom credentials, paste your Client ID and Client Secret, and Save.

3. The App Details panel on the CMS dashboard confirms the configuration:

• OAuth Client Type, confidential (because we registered a secret)
• OAuth Grant Type, authorization-code
• All callback URIs we registered
• Demographic data flag, Yes

Test with Sandbox Synthetic Users

CMS provides ~30 synthetic Medicare beneficiaries (BBUser00000 through BBUser00029, passwords PW00000! through PW00029!) with pre-populated claims. No real Medicare account is required, synthetic credentials are accepted by the CMS BB sandbox login flow.

Sandbox endpoints:

Test flow:

1. From your app, trigger a Medicare connect.
2. The browser redirects to sandbox.bluebutton.cms.gov/v2/o/authorize/?...&aud=https://sandbox.bluebutton.cms.gov/v2/fhir/.
3. CMS BB redirects to medicare.gov/account/login for SSO.
4. Sign in as a synthetic user, e.g. BBUser00001 / PW00001!.
5. On the CMS BB consent screen, click Connect.
6. CMS redirects to your registered callback with ?code=...&state=....
7. Your backend exchanges the code for tokens, Basic auth header with client_id:client_secret, plus code_verifier from PKCE.
8. Token response includes access_token, refresh_token, patient (synthetic beneficiary id, e.g. -10000010254647), scope. No id_token, fetch /v2/connect/userinfo with the access token to resolve identity.
9. Fetch Patient/{id}, Coverage?beneficiary=Patient/{id}, ExplanationOfBenefit?patient={id}. Synthetic users have 30+ EOB records each.

Known sandbox quirks:

• Rate limits are tighter than production (~10 req/s/app). The worker must handle 429 with Retry-After-aware backoff or you’ll see “Assembly Rate Limit exceeded” errors.
• No id_token, CMS BB does not issue id_tokens. Use the /v2/connect/userinfo endpoint instead, or use the patient claim from the token response and fetch Patient/{id} directly.

Apply for Production Access

CMS reviews every app individually before granting production credentials. The review takes 2–4 weeks and includes a live demo of the user journey.

Before contacting CMS, verify:

• Sandbox integration works end-to-end, at least one successful Patient + Coverage + EOB pull.
• Privacy policy is published at a stable URL and covers all CMS-required sections.
• Terms of service is published at a stable URL.
• Consent screen shows the inviting organization name (Shared with: <org>).
• Beneficiary can revoke access, either an in-app disconnect button or a documented email path (e.g. privacy@yourdomain.com) with a documented 30-day deletion SLA.
• Disconnect / revocation triggers /v2/o/revoke_token/ server-side and deletes locally retrieved Medicare data.
• CMS attribution disclaimer (“not endorsed by CMS”) is shown on the connect screen.

Send a production access request to BlueButtonAPI@cms.hhs.gov from the customer support email you registered on the sandbox app. CMS replies within a few business days with a request form and a link to schedule a demo.

At minimum include your sandbox client_id, your privacy policy URL, your terms of service URL, the list of production redirect URIs, and a one-paragraph description of what your application does with Medicare data. Anything else CMS needs they’ll ask for via the request form.

After approval, CMS schedules a 30–45 minute Zoom demo. Have ready: a live walkthrough of beneficiary signup, consent dialog, Medicare connection, data display, and revocation; your privacy policy and ToS open in another tab; your security writeup. CMS may request follow-ups on retention, the unlink workflow, or data sharing, respond within 48 hours.

Once approved, CMS issues a production client_id and client_secret via secure file transfer. In your Medblocks dashboard, go to Settings → Connections → Medicare, switch to Custom credentials, and paste the production values. The platform repoints the FHIR endpoints to production (https://api.bluebutton.cms.gov/v2/...) automatically.