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 1 of the 4 client ID and password sets provided in the sandbox credentials section. You’ll need to use the sandbox identity provider (test.idm.idp.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 (idp.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 1 hour 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 Z1001 (10,000 enrollees)

Client ID:

0oa9jyx2w9Z0AntLE297

Client password:

hskbPu-YoWfGDY1gcQq34BfIEyMVuayu87zWDliG

Base64-encoded credentials:

MG9hOWp5eDJ3OVowQW50TEUyOTc6aHNrYlB1LVlvV2ZHRFkxZ2NRcTM0QmZJRXlNVnVheXU4N3pXRGxpRw==

Sample contract Z1002 (10,000 enrollees)

Client ID:

0oa9jz0e1dyNfRMm6297

Client password:

shnG6NGkHcu29ptDsKKRW6q5uFJSSpIpdl_K5fVW

Base64-encoded credentials:

MG9hOWp6MGUxZHlOZlJNbTYyOTc6c2huRzZOR2tIY3UyOXB0RHNLS1JXNnE1dUZKU1NwSXBkbF9LNWZWVw==

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. In Confluence, use the code block macro. 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 PDP-100 as an example, the credentials are formatted as 0oa2t0lsrdZw5uWRx297:HHduWG6LogIvDIQuWgp3Zlo9OYMValTtH5OBcuHw.

AUTH=$(echo "${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 PDP-100 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 ${base64_encoded_credentials}")

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

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

The token is valid for 1 hour. 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:
   Code snippet: AUTH_FILE=/home/abcduser/credentials_Z123456_base64.txt OKTA_CLIENT_ID=abcd OKTA_CLIENT_PASSWORD=badpassword

   Copy

   AUTH_FILE=/home/abcduser/credentials_Z123456_base64.txt
   OKTA_CLIENT_ID=abcd
   OKTA_CLIENT_PASSWORD=badpassword

3. Encode the credentials as Base64.
   Code snippet: echo -n "$OKTA_CLIENT_ID:$OKTA_CLIENT_PASSWORD" | base64 > $AUTH_FILE

   Copy

   echo -n "$OKTA_CLIENT_ID:$OKTA_CLIENT_PASSWORD" | base64 > $AUTH_FILE

Powershell

1. Open a PowerShell terminal.
2. Create a new empty file.
   Code snippet: $AUTH_FILE=C:\users\abcduser\credentials_Z123456_base64.txt New-Item -Path $AUTH_FILE -ItemType File

   Copy

   $AUTH_FILE=C:\users\abcduser\credentials_Z123456_base64.txt
   New-Item -Path $AUTH_FILE -ItemType File

3. Create the Base64 credentials.
   Code snippet: $BASE64_ENCODED_ID_PASSWORD='{base64_encoded_credentials}

   Copy

   $BASE64_ENCODED_ID_PASSWORD='{base64_encoded_credentials}

4. Save the Base64 credentials as a single line in the authorization file.
   Code snippet: Set-Content -Path $AUTH_FILE $BASE64_ENCODED_ID_PASSWORD

   Copy

   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:

• How to Access Sandbox Data
• How to Access 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