How to Get a Bearer Token

Bearer tokens, also known as access tokens or JSON web tokens, authorize use of the Beneficiary Claims Data API (BCDA) endpoints. You will need a bearer token to access claims data in the sandbox and production environments.

Instructions

1. Get your organization’s credentials

BCDA protects its token endpoint with Basic Auth. Your credentials will be formatted as a client ID and client secret.

• Sandbox environment: Use a sample client ID and secret from the sandbox credentials section.
• Production environment: Use the client ID and secret issued by your model-specific system during production access. Credentials must be rotated (renewed) every 90 days.

2. Request a bearer token

Start a request for a bearer token in your terminal window or using a tool such as Postman. The following example uses the credentials of the extra-small model entity in BCDA’s sandbox environment:

Sample Credentials

Example client ID (Extra-Small Model Entities):

3841c594-a8c0-41e5-98cc-38bb45360d3c

Example client secret (Extra-Small Model Entities):

f8428de4a3c942ea655f2d8235607972638505d50b6b24cb54086e1fab9f28fcddb32747e1abc6de

Request header

The header has Authorization: Basic followed by the credentials. Credentials (client_id:client_secret) are joined by a colon, then encoded in Base64 format.

Authorization: Basic {base64_encoded_credentials}
Accept: application/json

Example curl command to request a bearer token

In this example, the authorization in the request header is replaced with --user {client_id}:{client_secret}.

This command uses curl’s built-in ability to Base-64 encode your credential to request and receive your token in a single step.

curl -d "" -X POST "https://sandbox.bcda.cms.gov/auth/token" \
	--user 3841c594-a8c0-41e5-98cc-38bb45360d3c:f8428de4a3c942ea655f2d8235607972638505d50b6b24cb54086e1fab9f28fcddb32747e1abc6de \
	-H "Accept: application/json"

Response example: successful request

If your request succeeds, you’ll receive a 200 response with your bearer token in the response body. It’ll be the full text string that follows “access_token.” The token string below has been abbreviated for readability.

“expires_in” counts down the seconds remaining before the token expires, which is 20 minutes after it is generated. “token_type: bearer” is a fixed value.

{
  "access_token": "eyJhbGciOiJSUzUxMiIsInR...",
  "expires_in": "1200",
  "token_type": "bearer"
}

3. Set your bearer token in your request headers

Include your bearer token in the authorization header when requesting data in the sandbox and production environments. “Bearer” must be included in the header with a capital B and followed by a space.

Authorization: Bearer {bearer_token}

Now you can begin accessing claims data. The production and sandbox environments support the same workflow, endpoints, and resource types.

Sandbox credentials

Sandbox credentials allow anyone to access synthetic test claims data. These credentials will not work in the production environment.

Sample data sets vary in size and data complexity, ranging from 50 to 30,000 synthetic enrollees, to best match the needs of your model entity.

Adjudicated claims data sets – 2 simple sizes

Use the data sets to test retrieving and downloading data files into your internal ingestion processes. However, the test data may not reflect an accurate distribution of disease and demographic information.

Extra-small model entity (50 synthetic enrollees)

Client ID:

3841c594-a8c0-41e5-98cc-38bb45360d3c

Client secret:

f8428de4a3c942ea655f2d8235607972638505d50b6b24cb54086e1fab9f28fcddb32747e1abc6de

Extra-large model entity (30,000 synthetic enrollees)

Client ID:

6152afb4-c555-46e4-93de-fa16a441d643

Client secret:

346cab049fee2cf8f3266faa1bf2ca0478e1529d68867e58636b0729467d6a95ba8d08c9000d2527

Adjudicated claims data sets – 2 advanced sizes

Advanced data sets offer a more accurate representation with the bulk FHIR format and a realistic distribution of disease and demographic information.

The small data set helps you understand the format of BCDA data. The large data set is better for in-depth exploration or early load testing of your systems.

Extra-small model entity (100 synthetic enrollees)

Client ID:

6dc59a4c-ef93-46c0-9c00-02e500e13731

Client secret:

f35cebee5b920711ea08cc08a6a7126b5176fa23ee341d39f3aa735eb755a33ea0c493c6cc950160

Large advanced model entity (10,000 synthetic enrollees)

Client ID:

f5b6a686-0d7b-4080-873a-e60534fd2995

Client secret:

9cc8e6b04349e678587eb38d58860e6728ff10c1124dbcd775fc247dc5f93ec583a78115445d6679

Partially adjudicated claims data sets

Anyone can access partially adjudicated claims data in the sandbox. Only REACH ACOs can access enrollees’ partially adjudicated claims data in production.

Extra-small REACH ACO (110 synthetic enrollees)

Client ID:

7e57394f-eddb-46c7-a87b-a23f14ded95d

Client secret:

3ab22e7faaf69fa2d572831ffc1db12252c6d569d3e1b54aecf56e075ba054c20fee83b2e013c9c3

Large REACH ACO (11,000 synthetic enrollees)

Client ID:

2121efbd-98d2-4323-84db-974c8864abc7

Client secret:

ee1b0609f024a758bf1770ec16f809330d2ba8bb4e9004a7868c0258accfd69ced5b6448188abb7b

Troubleshooting

Ensure that your bearer token is not expired.

• Bearer tokens expire after 20 minutes.
• Jobs will not be interrupted when the bearer token expires. In progress and queued jobs will continue to run.
• You do not need to start a new job if your bearer token expires and your job was completed in the last 24 hours. You can download these files using a new bearer token. After 24 hours, the files will expire and you will need to restart the job.

Ensure that your production credentials are not expired.

Credentials must be rotated (renewed) every 90 days. Learn more about credentials and production access.

Remember to use the correct URL for your environment.

Use sandbox.bcda.cms.gov to access the sandbox or api.bcda.cms.gov to access the production environment.