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):

2462c96b-6427-4efb-aed7-118e20c2e997

Example client secret (Extra-Small Model Entities):

e5bf53ec3a4304ab43c00155cfe1f01a00a6f6003ad07d323b3b6bce9ad4ae5b137ef4e8509d881b

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 2462c96b-6427-4efb-aed7-118e20c2e997:e5bf53ec3a4304ab43c00155cfe1f01a00a6f6003ad07d323b3b6bce9ad4ae5b137ef4e8509d881b \
	-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:

2462c96b-6427-4efb-aed7-118e20c2e997

Client secret:

e5bf53ec3a4304ab43c00155cfe1f01a00a6f6003ad07d323b3b6bce9ad4ae5b137ef4e8509d881b

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

Client ID:

aa2d6b93-bbe7-4d1b-8cc5-9a5172fae3a6

Client secret:

97755772b3fb7b3fa2f58c5c3aaaffbc7e346639ff8da371a81adf79889c8fbd4c40398cd39d211d

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:

e75679c2-1b58-4cf5-8664-d3706de8caf5

Client secret:

67570807508212a220cc364d4406b9bd560276142d46257f76ba28dd9a0ff969e0c26db21c9d925c

Large advanced model entity (10,000 synthetic enrollees)

Client ID:

0a0c75f0-da95-4198-9c0f-666b41e21017

Client secret:

c637024fa21adda5a756a2753cf7eb9bd62292e7897fb965a5c7aeeed23e1728ddc9ec6863f09f15

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.