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 Small Advanced Model Entity in BCDA’s sandbox environment:

Sample Credentials

Example client ID (Small Advanced Model Entity):

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

Example client secret (Small Advanced Model Entity):

48fe3a3731ee5b68cf4ebeea6d93fa2d9db3396e94f6830f17d7d7c0fa1fb61f413fcde6f6322f84

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 6dc59a4c-ef93-46c0-9c00-02e500e13731:48fe3a3731ee5b68cf4ebeea6d93fa2d9db3396e94f6830f17d7d7c0fa1fb61f413fcde6f6322f84 \
	-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 100 to 11,000 synthetic enrollees, to best match the needs of your model entity.

Adjudicated claims data sets – 2 advanced sizes

Advanced data sets offer an 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:

48fe3a3731ee5b68cf4ebeea6d93fa2d9db3396e94f6830f17d7d7c0fa1fb61f413fcde6f6322f84

Large advanced model entity (10,000 synthetic enrollees)

Client ID:

f5b6a686-0d7b-4080-873a-e60534fd2995

Client secret:

96ac1483449c652f363396737937f23cdae47a56a116c8a4405dbd54b31d2686f005df502c5c86ab

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:

2c5130031150cd43afdc24659de2210086f6115fc8d897d7547faaa26c827b53bb70c14089bdeb17

Large REACH ACO (11,000 synthetic enrollees)

Client ID:

1f4575c9-80ea-425c-9d3e-c2b79e9159da

Client secret:

78389f5e9a9148cfd14832b4dfa89d8ebf3d09e178763ec3cdfee1373068e3b60f66c1bed2c14025

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.