The API's support a few different methods of authentication in addition to the normal session-based authentication used on the rest of CommCare HQ. This makes it easy to access these URLs programmatically.

The examples below use cURL

Basic authentication

See Wikipedia for details of basic authentication.

Example (will prompt for the password):

curl -v -u [USERNAME] '[URL]'

You can also include the password in the command as follows:

curl -v -u [USERNAME]:[PASSWORD] '[URL]'

Digest authentication

See Wikipedia for details of digest authentication.

Similar to Basic auth but add the --digest parameter:

curl -v --digest -u [USERNAME] '[URL]'

Api Key authentication

Your API Keys can be found at https://www.commcarehq.org/account/api_keys/

From that page you can generate new API keys and scope them to individual IP addresses. If an API key has an IP address whitelist, any request originating from a different IP address that uses that API key will be rejected.

When an API key is deleted, all requests using that key will be rejected. Unfortunately deleted keys cannot be recovered.

When creating a new API key, the actual key will only be shown once so you should note it down at that moment.

If you use this method of authentication, you do not need to provide a 2 factor OTP header (this is only relevant for API calls with 2 factor auth required.)

curl -H "Authorization: ApiKey [USERNAME]:[API_KEY]" '[URL]'
  • No labels

1 Comment

  1. Anonymous

    POST requests seem to still use Basic Authentication:

    curl -v --user [USERNAME]:[PASSWORD] '[URL]'