Authentication
Administrator API functions require a valid api_key. Include it in the query string for HTTP GET requests or the request body for JSON POST and SOAP requests.
WebstudyCredit uses the study's credit_token instead. It does not require an administrator API key.
API keys are user-specific and can be generated as follows:
Navigate to the Users | Add/Edit/Search section on your main site.
Find the user for whom you want to generate an API key.
Click on the "Set API Key" button next to the user's information.
On the "Set API Key" page, click "Set API Key" to generate a new key for that user.
Each administrator can have their own API key for access control and usage tracking.
Authentication Errors¶
Listed below are the different authentication error codes along with their description.
| Error Code | Description |
|---|---|
| 0 | unspecified error |
| -1 | bad username/password* |
| -2 | bad user type (not an admin) |
| -3 | access not allowed (account disabled) |
| -4 | user not found |
| -5 | access prevented due to password account lockout |
| -6 | reach API key limit |
| -7 | bad API key |
* Username/password access has been deprecated and removed.
These error codes apply only if the API key authentication fails. If it works OK, then the return will merely be the typical return value from the API call (and unrelated to authentication).
Username and Password API Authentication Removal¶
To enhance the security of the Sona platform and better support users accessing Sona via Single Sign-On (SSO), username and password authentication for API access was deprecated and has now been removed.
Use an administrator API key for administrator API functions. For WebstudyCredit, use the study's generated completion URL and credit_token.