CMS Aligned Networks Developer Documentation

Prerequisites

• Application has met the requirements and has been listed in the Medicare App Library
• Application has provided a URL to JWK Set to the Blue Button API team

Approach

For applications that are approved as part of a CMS Aligned Network, Blue Button API will allow for the use of the client_credentials grant, in combination with asymmetric authentication, to receive an access token. When using this flow, a beneficiary will not be required to log in via medicare.gov. A diagram of the flow is below. This is in contrast to the existing authorization_code + symmetric authentication flow requiring a portal login.

Technical Requirements

Blue Button API will only accept the client_credentials grant type when an extension, cms_smart, is present in the authentication JWT claims.

cms_smart is modeled off the tefca_smart extension that was present in the 2024 Facilitated FHIR Implementation Guide.

Parameters

Parameters in POST request to Blue Button API’s /token endpoint for CMS-aligned networks flow:

POST to Blue Button API /token endpoint:

Header: "Content-Type": "application/x-www-form-urlencoded"

Example Parameters:

{
  "grant_type": "client_credentials",
  "scope": "patient/Patient.rs patient/Coverage.rs patient/ExplanationOfBenefit.rs launch/patient openid profile",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "{YOUR_JWT_HERE}"
}

Authentication JWT Header

Authentication JWT Claims

cms_smart Extension Definition

Example decoded JWT containing the cms_smart extension:

Example Header:

{
  "alg": "RS384",
  "kid": "my-key-id-1",
  "typ": "JWT"
}

Example Claims:

{
  "iss": "my-client-id-1",
  "sub": "my-client-id-1",
  "aud": "https://test.bluebutton.cms.gov/v3/o/token",
  "jti": "8b4b7fab-93ed-4e59-9935-f9244d90b516",
  "exp": 1774651583,
  "extensions": {
    "cms_smart": {
      "version": "1",
      "purpose_of_use": "PATRQT",
      "id_token": "{YOUR_ID_TOKEN_HERE}"
    }
  }
}

ID Token Requirements

Blue Button API will perform patient matching based upon the presence of an IAL2 id_token provided by a registered client application. It will seek specific fields in the id_token’s claims.

Only CLEAR and ID.me are supported at the outset. Blue Button API’s sandbox environment will only accept ID tokens issued by CLEAR or ID.me’s lower environments, and Blue Button API’s production environment will only accept ID tokens issued by CLEAR or ID.me’s production environments.

ID Token JWT Header

ID Token JWT Claims

Address Fields

Using the Blue Button API

After successfully POSTing a token to Blue Button API’s /token endpoint, it will attempt to find a unique match using the approved CMS matching algorithms. If a unique match is found, then an access token will be issued, with a token validity of 30 minutes, and refresh capability of up to 24 hours. If no match is found, an error will be returned to that effect.

Access tokens issued using this flow have the same capabilities of access tokens issued using the portal login authorization_code flow. To query for claims, coverage, or patient data, utilize the Patient, ExplanationOfBenefit, and Coverage resource paths:

• /v3/fhir/ExplanationOfBenefit/
• /v3/fhir/Patient/
• /v3/fhir/Coverage/

In addition, a new operation exists to pull in digital insurance card elements per the C4DIC Implementation Guide:

• /v3/fhir/Patient/$generate-insurance-card

CLEAR and ID.me Test account information

CLEAR Test Patients

• CLEAR Synthetic Test Identities & Patients

ID.me Test Patients

Patient Matching Criteria

Approved field combinations that Blue Button API currently supports:

• First Name + Last Name + DOB + Street Line
• First Name + Last Name + DOB + SSN Last 4
• First Name + DOB + MBI