Authentication

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):

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

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.

Open

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.)

Two-Factor authentication

If you have two factor authentication (2FA) set up on your account, then basic authentication is not directly supported for accessing APIs. Instead, you must use Api Key authentication, as described above, or pass in a two factor token generated via SMS or your authenticator application via the "otp" url parameter. For example: https://www.commcarehq.org/a/<domain>/api/v0.5/case/?otp=123456