Getting Started
Authentication
API key
- Go to your account page on Listen and open the Developer section. Admins can create API keys.
- Select Create API key. Copy the key. The key is shown only once.
- Use it in your request in the
x-api-keyheader.
Each API key is scoped to a single workspace. It works with all versioned API endpoints (/api/public/v1/...), such as studies, questions, wallets, and responses. It also works with the legacy endpoints (/api/public/responses, /api/public/list_surveys, and /api/public/studies/{study_id}/questions).
How keys work
- A key acts as an admin of its workspace. It can read, change, and delete every study in the workspace, including restricted studies.
- A key can't reach any other workspace.
- A key belongs to the workspace, not to the user who created it. It keeps working after that user leaves the workspace. Delete the key to stop it.
- Changes made with a key are recorded under the user who created it while they are a member, and otherwise under a workspace admin.
- A workspace can have up to 25 API keys. You can't create another key until you delete an unused one.
- The full key is shown only once, when you create it. Listen stores only a hash of the key. If you lose a key, create a new one and delete the old one.
Revoke a key
- In the Developer section, select the delete icon next to the key.
- Select Delete to confirm.
Requests that use the key stop working right away. You can't undo a deleted key.