Listen LabsDocs

    Getting Started

    Authentication

    API key

    1. Go to your account page on Listen and open the Developer section. Admins can create API keys.
    2. Select Create API key. Copy the key. The key is shown only once.
    3. Use it in your request in the x-api-key header.
    'x-api-key': 'abc123....'

    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

    1. In the Developer section, select the delete icon next to the key.
    2. Select Delete to confirm.

    Requests that use the key stop working right away. You can't undo a deleted key.