Authentication when using DET

Two sets of credentials are required:

  1. CommCareHQ credentials: a Username and an API Key.

  2. Database credentials (if outputting to a database). The database user must have access to create new tables, create new columns in those tables, and read and edit data.

CommCare HQ Authentication Requires an API Key

API Key authentication method is required. Each user must create their own API key and store it securely. 

  • API Keys can be scoped (restricted) to a domain or a set of domains

  • API Keys can also be set to an Allow-List IP Address or list of IP Addresses. 

  • IP Ranges are not permitted. Each individual IP address will need to be named. If you leave this blank, API requests from all IP addresses in the world will be allowed.

  • Create an API key: https://www.commcarehq.org/account/api_keys/

  • API keys belong to individual web users. Each user who wants to run a Data Export Tool query will need their own API key.

Enterprise Domains

  • When using domains that are linked to a main account, whose permissions inherit from the main account, the user doesn’t need to accept the invitation on all the domains. 

Security Recommendations

  • Store API Key name and password in a password manager.

  • Do not share your API key with anyone.

  • Do not email it to yourself or store it in any document that is not password-protected.

  • Rotate keys: Create new API Keys each month and name the API Key by the month.

Referencing API Key From Command Line

To use API Key authentication in Data Export Tool from the command line, the following two parameters are required:

  • --auth-mode: "apikey"

  • --username: set to the web user's email (e.g. username@email.com)

  • --password: set to the API Key generated above

An example call might look like:

C:\Python39\Scripts>commcare-export --output-format xlsx --output YOUR_OUTPUT_FILE_NAME.xlsx --project YOUR_PROJECT --query YOUR_QUERY_FILE_NAME.xlsx --username username@email.com --auth-mode apikey --password ***********YOUR_API_KEY**************