Skip to main content

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

AB2D v3 is here!

Read the full announcement on AB2D v3 or learn how to migrate. Access to v1 and v2 will be removed on July 30, 2027.

How to Get a Bearer Token

Bearer tokens, also known as access tokens or JSON web tokens, authorize use of the AB2D endpoints. You will need a bearer token to access the sandbox and production environments. Once you have a bearer token, follow the instructions to access either sandbox data or production claims data.

Instructions

  1. You can use a variety of tools to get a bearer token, including curl. AB2D uses Okta to authenticate your organization's credentials, which will be a client ID and password.
    • If you’re trying to access sandbox data: Use either of the client ID and password sets provided in the sandbox credentials section. You’ll need to use the sandbox identity provider (test.idp.idm.cms.gov).
    • If you’re trying to access production data: Once you complete the steps for production access, the AB2D team will send your Attestor a credentials file with your production client ID and password. You’ll need to use the production identity provider (idm.cms.gov). You can also create your own credential file manually.
  2. Once you have your sandbox or production credentials, create a new text file using your editor of choice.
  3. The credentials (clientID:password) must be encoded in Base64 format. Paste the Base64-encoded string into the new text file. It should only be a single line.
  4. Start a request for the bearer token, using your Base64-encoded string as the authorization. The request will look similar to our example: 
    POST https://test.idp.idm.cms.gov/oauth2/aus2r7y3gdaFMKBol297/v1/token
Headers:
        Content-Type: application/x-www-form-urlencoded
        Accept: application/json
        Authorization: Basic {base64_encoded_credentials}
Parameters:
        grant_type: client_credentials
        scope: clientCreds
  5. The response will contain your bearer token. The token will be sent using the “Authorization” header field with “Bearer {XXX}” where {XXX} is the value of the token: 
    Bearer {bearer_token}
    Bearer tokens expire 30 minutes from the time they are obtained. Use the token quickly to request your claims data. If your token expires, you’ll need to restart the process.
  6. Save this as the credential file (e.g., C:\users\abcduser\credentials_Z123456_base64.txt). Note the file’s location and name for later. It will be a parameter in other scripts.

Sandbox credentials

Anyone can try the API and download test data using sample contracts in the sandbox. Sandbox credentials will not work in the production environment.

Sample contract Z0003 (10,000 enrollees)

Client ID:

0oa9jyy4ou5c1MJ3N297

Client password:

PUvA2UrGiKSanrumb5p3hhacGzdZrPxfW4lheVY8

Base64-encoded credentials:

MG9hOWp5eTRvdTVjMU1KM04yOTc6UFV2QTJVckdpS1NhbnJ1bWI1cDNoaGFjR3pkWnJQeGZXNGxoZVZZOA==

Sample contract Z0004 (10,000 enrollees)

Client ID:

0oa9jyw49f9U19vvB297

Client password:

bSKGteVvesj9cCpkTHqEINX-aaiHy2NjuPAnX1Ao

Base64-encoded credentials:

MG9hOWp5dzQ5ZjlVMTl2dkIyOTc6YlNLR3RlVnZlc2o5Y0Nwa1RIcUVJTlgtYWFpSHkyTmp1UEFuWDFBbw==

How to get a bearer token using curl

Learn how to get a bearer token for the sandbox using the curl command line tool specifically. You can copy and paste these commands into your terminal. Learn how to install curl and jq.

HTTP responses are saved into shell variables named RESP<n>. Most steps also define shell variables used later in the process. For educational purposes it can be useful to examine variable values by entering echo ${VARIABLE}.

I. Encode client credentials into Base64

Encode the credentials (clientID:password) into Base64, and set the AUTH shell variable. Using contract Z0003 as an example, the credentials are formatted as 0oa9jyy4ou5c1MJ3N297:PUvA2UrGiKSanrumb5p3hhacGzdZrPxfW4lheVY8.

AUTH=$(echo -n "${OKTA_CLIENT_ID}:${OKTA_CLIENT_PASSWORD}" | base64)

II. Get your bearer token

Enter this command to make an HTTP request and set the RESP1 variable. The full Base64-encoded credentials for Z0003 and Z0004 are listed above, but will look something like MG9hMnQwbHNyZ…VHRINU9CY3VIdw==.

RESP1=$(curl -X POST "https://test.idp.idm.cms.gov/oauth2/aus2r7y3gdaFMKBol297/v1/token?grant_type=client_credentials&scope=clientCreds" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -H "Authorization: Basic ${AUTH}")

This extracts the token from the previous response and sets the BEARER_TOKEN variable needed by all subsequent API requests.

BEARER_TOKEN=$(echo $RESP1 | jq -r ".access_token")

The token is valid for 30 minutes. If it expires, repeat the process for a new token.

How to create a credential file

Once you obtain production access, you can either create a Base64-encoded clientID:password manually from your production credentials or use the file the AB2D team sent for convenience.

In this example, we use “Z123456” as the contract number, “abcd” as the client ID, and “badpassword” as the password. When encoded, the example client ID and password would look like YWJjZDpiYWRwYXNzd29yZA==. Your credentials will likely be a little longer, but this gives you an idea of what the value looks like.

Linux or Mac

  1. Create a file in a directory for the Base64 credentials. Make sure you have write access to that directory. This example will use credentials_Z123456_base64.txt in the /home/abcduser directory.
  2. Open a Bash terminal and enter the following command: 
    AUTH_FILE=/home/abcduser/credentials_Z123456_base64.txt
OKTA_CLIENT_ID=abcd
OKTA_CLIENT_PASSWORD=badpassword
  3. Encode the credentials as Base64. 
    echo -n "$OKTA_CLIENT_ID:$OKTA_CLIENT_PASSWORD" | base64 > $AUTH_FILE

PowerShell

  1. Open a PowerShell terminal.
  2. Create a new empty file. 
    $AUTH_FILE='C:\users\abcduser\credentials_Z123456_base64.txt'
New-Item -Path $AUTH_FILE -ItemType File
  3. Create the Base64 credentials. 
    $BASE64_ENCODED_ID_PASSWORD='{base64_encoded_credentials}'
  4. Save the Base64 credentials as a single line in the authorization file. 
    Set-Content -Path $AUTH_FILE $BASE64_ENCODED_ID_PASSWORD

Guides

Once you get a bearer token, you can access either sandbox or production claims data:

Troubleshooting

Visit our Troubleshooting Guide to explore HTTP response codes and common questions. If you need additional assistance, email the AB2D team at ab2d@cms.hhs.gov.

When contacting our team, please include the following information:

  • Your operating system
  • If applicable, your HTTP response code (e.g., 403, 400)
  • A description of the issue including which stage of the process you’re on
  • Any logs that may help us in resolving the issue

cms.gov

official website of the U.S. Department of Health and Human Services and the Centers for Medicare & Medicaid Services.

Looking for U.S. government information and services?
Visit USA.gov