Authentication

API Keys

Learn how to create and manage API keys. The same key works on both the REST API and the GraphQL API.

Creating an API Key

1. Open Settings → Developers
2. Under API Keys, click Add API Key
3. Give the key a description — the integration it is for is a good one — and click Create API Key
4. Copy and store your key securely — you will not be able to see this again so make a note

New keys begin audioaudit_api_, so they're recognisable in a config file or a log line; a key created before the prefix was introduced has none and keeps working unchanged.

A key is created in one workspace — either your personal workspace or a single Organisation — and it is the workspace selected in Settings when you create it. To create one for a different workspace, change it first with the switcher at the top of the workspace section in Settings. A key created against an Organisation acts as one of that Organisation's owner accounts — an arbitrary one if it has several, and not necessarily the same one after the owners change.

You can always create keys for your personal workspace. In an Organisation, only Owners can create keys, along with any member an Owner has given the Developer access: API keys and webhooks permission. Being an Admin is not enough on its own, because an organisation key acts with an Owner's authority.

On the REST API the key is the workspace: there is no workspace parameter on any endpoint, and an Organisation key reaches that Organisation and nothing else.

On the GraphQL API the workspace is an argument you pass. Queries return the acting account's personal workspace unless you explicitly ask for the Organisation's data with organisationId, and a key can reach any workspace the account it acts as belongs to — so choose the organisationId you want rather than assuming the key confines you to one. See Workspaces for how to do that.

Create separate keys per integration if you want to revoke them independently.

Using API Keys

Include your API key in the Authorization header:

Authorization: Bearer your-api-key-here

Testing Your API Key

The quickest check is the REST API's GET /me, which returns the workspace the key is bound to:

curl https://audioaudit.io/api/rest/v1/me \
  -H "Authorization: Bearer your-api-key-here"

A 200 names the workspace — workspace.type is personal or organisation — along with the key's own record. A 401 with the code invalid_api_key means the key is wrong, has been disabled, or belongs to an Organisation with no owner.

On the GraphQL API, fetch the account the key acts as:

curl -X POST https://audioaudit.io/api/graphql \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { user { id email firstName lastName } }"
  }'

You should see a GraphQL response with an id, email, firstName and lastName. For a personal key that is your own account; for an Organisation key it is one of the accounts that owns the Organisation.

Once that works, head to the REST API reference for the endpoints that list your series, create reports and read their results, or to the GraphQL API page if you are building on GraphQL.

Security Best Practices

• Never expose API keys in client-side code
• Rotate keys regularly
• Use different keys for different environments and applications