Authentication
How to authenticate requests to the Soundwaves API with personal API keys, connected apps or a site key.
The API accepts a few kinds of credential. Pick the one that matches who is calling.
| Caller | Credential | How to send it |
|---|---|---|
| Your own scripts and tools | Personal API key | Authorization: Bearer <key> |
| An AI assistant or third-party app acting for you | Connected app (OAuth) | Handled by the app after you approve it |
| A listener-facing website or app | Site key | Coming soon, see Site keys |
Personal API keys
A personal API key acts as you, within the organisation you create it for. Create one from your Soundwaves account’s security settings.
- Every key has an expiry date.
- You can narrow a key to fewer permissions than you hold, so a reporting script can’t change anything.
- Keys are shown once when created. Store them like a password.
- You can revoke a key at any time. If a key is ever found exposed, it is marked compromised and stops working until you reissue it.
curl https://api.staging.swztech.net/graphql \
-H "Authorization: Bearer $SOUNDWAVES_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "{ me { email } }" }'Permissions
What a credential can do is decided by the permissions of the person behind it, narrowed by the key. The reference lists the permission each field needs. If a request is missing one, the API returns a FORBIDDEN error rather than partial data. See Errors and limits.
Some actions are sensitive enough that the API asks you to confirm it’s really you before they go through. Those return a STEP_UP_REJECTED error when called with a stale session.
Connected apps
When an AI assistant or other app connects to Soundwaves, you approve it on a consent screen and choose what it can access. You can see and disconnect your connected apps from your account’s security settings. See AI assistants.