Authenticate

The COVID-19 Data Clearinghouse REST API uses authentication tokens to allow registered users to access REST API resources on the CDC server (https://covdch-api.cdc.gov).

First, you need to obtain a Client ID (user name) and Secret (password) from your designated Data Clearinghouse administrator.

If you don't have a Client ID and Secret: Reach out to your administrator to get that information. Next, you need to store the Client ID and Secret in a safe place, so you can use them to authenticate later.

If you have the Client ID and Secret: Follow these steps to make sure you are ready to to authenticate:

1. Reach out to your administrator to make sure you are provisioned to use the Data Clearinghouse REST API.
2. Double-check that your cURL is set up the right way. For more details, see Use cURL.

If you need further help authenticating, contact your Data Clearinghouse administrator.

Obtain a token: Next, use your credentials (Client ID and Secret) to get a token using the REST API token generation endpoint (POST https://covdch-api.cdc.gov/v0/token/gen). The token is passed in a header each time you access a REST API resource.

A token is valid for 15 minutes. If your work will take longer than 15 minutes, remember to get a new token (POST https://covdch-api.cdc.gov/v0/token/gen) or refresh the existing token (POST https://covdch-api.cdc.gov/v0/token/refresh) before the token expires.

For example, to authenticate using cURL:

• Provide the server and endpoint:

  curl -X POST -s "https://covdch-api.cdc.gov/v0/token/gen"

• Pass the request and response type headers using the -H cURL option.

  -H "accept: application/json" 
  -H "Content-Type: application/json" 

• Pass the Client ID and Secret using the -d cURL option.

   -d "{"clientID":"<your client ID>","clientSecret":"<your client secret>","scopes":["<scope 1>","<scope 2>","<scope n>"]}"

• A scope is a permission your administrator sets on your account to allow you to do a specific function. For example, assume this user needs to upload files and export from the non-redacted database. The required scopes would be UPLOAD and EXPORT_NON_REDACTED.

  Note:

  If you are doing work on behalf of another client, append the onBehalfOfClientID parameter with the Client ID of the party you are working for.

  All scopes:

  • UPLOAD: Client can upload new immunization records.
  • DELETE: Client can upload delete immunization record requests.
  • UPDATE: Client can upload updated immunization record requests.
  • EXPORT_REDACTED: Client can export immunization records from the Data Clearinghouse redacted database.
  • EXPORT_NON_REDACTED: Client can export immunization records from the Data Clearinghouse non-redacted database.
  • EXPORT_SUMMARIZATION: Client can download the file upload history to the CDC IZ Data Lake by date range and jurisdiction.

The following provides the above example of the complete cURL command:

curl -X POST -s "https://covdch-api.cdc.gov/v0/token/gen" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-d "{"clientID":"<your client ID>","clientSecret":"<your client secret>","scopes":["UPLOAD","EXPORT_NON_REDACTED"]}"

Response:

{
  "token": "<string>",
  "expiration": <date code>
}