Production credentials authorize your organization's access to the Beneficiary Claims Data API (BCDA). Eligible model entities can manage BCDA credentials by logging into their model-specific system:

• ACOs in the Medicare Shared Savings Program: Credential delegates can manage and create credentials from ACO Management System (ACO-MS).
• REACH ACOs and KCEs or KCF practices in the Kidney Care Choices Model: The following roles can manage and create credentials from 4innovation (4i):
  • Executive Contact
  • Entity Primary Contact
  • Entity Secondary Contact
  • DUA Requestor
  • DUA Custodian

Your registered contact can contact the ACO-MS and 4i help desk to assign these roles.

Create your credentials

BCDA credentials are formatted as a client ID and secret, which your organization will use every time it requests an authentication token. Production credentials are sensitive information and must be stored securely.

Create BCDA credentials by visiting the API Credentials page in your model-specific system. Choose the BCDA Credentials tab, then select Create New API Credentials. You'll need to provide a public, static IP address for every system, including vendors, that will access the API (up to 8 IP addresses). It may take up to an hour for the allow list to be updated.

Rotate your credentials

Your organization's credentials will expire and deactivate after a set period of time. You can rotate BCDA credentials in the API Credentials page to generate a new, active client ID and secret.

You'll need to rotate credentials every 90 days in 4i or ACO-MS. Once you choose the BCDA Credentials tab, select the rotate icon under the Actions column.

Revoke your credentials

You may need to revoke (deactivate) your organization's credentials if they are leaked or compromised. You can create new credentials as a replacement afterward.

Revoke BCDA credentials in the API Credentials page. Choose the BCDA Credentials tab, then select the delete (x) icon under the Actions column.

If your credentials have been compromised

Please revoke or rotate your BCDA credentials immediately. Afterward, notify the BCDA team at bcapi@cms.hhs.gov to review recent activity.

Currently, access tokens expire after twenty minutes. To illustrate this cycle, we’ll use the published open sandbox credentials for Extra-Small Model Entities.

Example Client ID (Extra-Small Model Entities):
2462c96b-6427-4efb-aed7-118e20c2e997

Example Client Secret (Extra-Small Model Entities):
8e87f0ebc50d10f1bc9734329a9900179b84ccd39e4d0920b905cc359cf6e94a6e760bbe3a0890c7

Submit your credentials to receive an Access Token

You will need to submit the Client ID and the Client Secret issued to your organization using a POST request. You will receive an Access Token that allows access to the API for 20 minutes before expiring.

Access Token Request

POST /auth/token

Access Token cURL Command

This command takes advantage of curl’s built-in ability to Base-64 encode your credentials, request, and receive your token in a single step. The authorization in your request header will be substituted with "--user {client_id}:{client_secret}"

curl -d "" -X POST "https://sandbox.bcda.cms.gov/auth/token" \
	--user {client_id}:{client_secret} \
	-H "accept: application/json"

Access Token Response Example

The token string below has been abbreviated for readability.

{
"access_token": "eyJhbGciOiJSUzUxMiIsInR5c...",
"token_type":"bearer"
}

Access Token Response Headers

access_token: The full text string will serve as your access token. token_type: A fixed value as “bearer”.

Access Token Explanation

In cURL Option 1, you must base-64 encode the Client ID and Secret. Once that is performed, the encoded credentials can be passed to cURL as a header with the form: authorization: Basic [Base64-encoded clientId:secret]

In cURL Option 2, the user can take advantage of cURL’s built-in ability to base-64 encode the clientId and secret, and request and receive their token in a single step. If your operation succeeds, you will receive a 202 response with your access token as a header. You will receive a 401 Unauthorized response if your credentials are invalid or if your token has expired. No additional information is returned with a 401 response. When you receive a 401 response for a token you were just using successfully, you should request a new access token as outlined above.

Set your Access Token as a Bearer Token

In all of your requests, set your access token as the Bearer token. The Bearer token is included in the header of any requests as follows:

Authorization: Bearer {access_token}

Notice that the word “Bearer” must be included with a capital B and followed by a space.

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Send a Request to Cancel a Job

Request to Cancel a Job

DELETE /api/v2/jobs/{job_id}

Request Headers

Authorization: Bearer {access_token}

Cancel a Job Explanation

This operation will send a request to cancel any active job. You may want to do this for very long-running jobs or to preserve resources.

If the request is successful, the active job will be terminated and a 202 response will be returned.

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Send a Request to the Jobs Endpoint

Requests to retrieve data on all past jobs

GET /api/v2/jobs

Request Headers

Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async

cURL Command to check the job status

curl -X GET "https://api.bcda.cms.gov/api/v2/jobs" \
    -H "accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {access_token}"

Response Example: Completed Job

{
    "entry":[
        {
            "resource":{
                "executionPeriod":{
                    "end":"2021-08-14T00:07:48+00:00",
                    "start":"2021-08-13T00:07:48+00:00"
                },
                "identifier":[
                    {
                        "system":"http://bcda.cms.gov/api/v2/jobs",
                        "use":"official",
                        "value":"1"
                    }
                ],
                "input":[
                    {
                        "type":{
                            "text":"BULK FHIR Export"
                        },
                        "valueString":"GET https://bcda.test.gov/this-is-a-test"
                    }
                ],
                "intent":"order",
                "resourceType":"Task",
                "status":"completed"
            }
        }
    ],
    "resourceType":"Bundle",
    "total":1,
    "type":"searchset"
}

Retrieve Historical Data on Past Job Requests Explanation

This operation will return a Bundle of resources containing information about jobs sent by your organization historically. Each resource represents a single job request. Notice that each resource contains a start date/time, an end date/time, a unique identifier, and the original request (contained in valueString).

Your jobs in the BCDA system have nine possible end states: Completed, Archived, Expired, Failed, FailedExpired, In Progress, Pending, Cancelled, and CancelledExpired. Notice that, in the above example, we did not supply any parameters; we’ve made an unfiltered request for all past jobs. To filter by the status of the job, you may supply a ‘status’ parameter. However, the status parameter has only four possible values supported by the FHIR Task resource: Completed, Failed, In Progress, and Cancelled.

The nine possible job states map to the four supported FHIR Task status values as follows:

• Archived, Expired, Completed -> Completed
• FailedExpired, Failed -> Failed
• Pending, In Progress -> In Progress
• CancelledExpired, Cancelled-> Cancelled

For example, if your organization had jobs Archived in the BCDA system, you could make a filtered request for those as follows: GET /api/v2/Jobs?_status=Archived. You would receive a list of jobs with the status “Completed”. All of these jobs were Archived in the BCDA system. If your organization also had jobs with the end state of Expired or Completed in the BCDA system, they would also hold the status of Completed. But, they would not be returned in your request for Archived jobs.

If your organization has no jobs to return, you will receive a 404 ERROR in your response.

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Send a Request to the Attribution Status Endpoint

Requests to check the last updated date of your attribution data

GET /api/v2/attribution_status

Request Headers

Authorization: Bearer {access_token}
Accept: application/json

cURL Command to retrieve the attribution status

curl -X GET "https://api.bcda.cms.gov/api/v2/attribution_status" \
	-H "accept: application/json" \
	-H "Authorization: Bearer {access_token}"

Response Example

{
    “Ingestion_dates”: [
        {
            “type”: “last_attribution_update”,
            “timestamp”: “2020-12-22 22:31:40.397916+00”
        },
        {
            “type”: “last_runout_update”,
            “timestamp”: “2020-12-22 22:31:40.397916+00”
        }
    ]
}

Check the Last Updated Date of your Attribution Data Explanation

This operation will return a timestamp of the last time your attribution data was updated in the BCDA system. You may want to use this timestamp to check whether to run a new job request. You can do so by comparing it to the last date/time your organization requested data from BCDA.

If BCDA has never ingested an attribution file or a runout file for your organization, you will receive a NOT FOUND 404 response.