Skip to content

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
  4. Choose what the key can do. Limited is the default and starts with every group you are allowed to give ticked; untick whatever the integration doesn't need. Or choose Full access — see Limiting what a key can do below
  5. Click Create API Key
  6. 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 full-access 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. A limited key is held to the permissions you ticked, whichever owner it acts as. Every organisation key, limited or not, is attributed to one of the owners, and stops working with 401 invalid_api_key if the Organisation has no owner.

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 a full-access 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. A personal key reaches your personal workspace by default and any Organisation you belong to through organisationId. An Organisation key reaches its own Organisation only: it must pass that Organisation's id as organisationId, and a call that leaves it out, names another Organisation, or asks about the owner account itself is refused. See Workspaces for how to do that. A limited key is pinned to the workspace it was created in as well: a limited personal key reaches only your personal workspace.

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

Limiting what a key can do

A key is either full access or limited. A full-access key does everything its owner can, which for an Organisation key means everything an Owner can inside that Organisation: roles and the team included, though not billing, plans or payment. Keys created before limits existed are full access and keep working unchanged. A limited key can do only what you ticked. You can only tick permissions you hold in that workspace, but a limited key applies them to every show in the workspace — there are no per-show limits — so a member who can see one show can make a key that reads them all. Anyone with developer access can also create a full-access key, which acts as an owner.

Pick the permissions in groups when you create or edit a key (a single Show individual permissions toggle opens every group into its individual permissions):

GroupPermissions it holds
View shows and reports (always on)series.view — See podcasts and their reports
Run reportsseries.report — Run reports on podcasts; org.report — Run reports on uploaded files
Enhance audioseries.enhance — Enhance podcast audio; org.enhance — Enhance uploaded files
Edit show settingsseries.edit — Edit podcast settings
Manage webhooksorg.developer — Manage webhooks
  • View shows and reports is always included: a key that can't see anything is no use, so it is added to any limited key.
  • Manage webhooks lets the key add, edit, test and delete webhook endpoints, including through the webhook subscribe calls. It never lets a key create, change or delete API keys.
  • You can only give a key permissions you hold yourself in that workspace. A member who can't edit show settings can't make a key that can. You can still untick permissions on a key someone else made, but not tick ones you couldn't grant.
  • A key's permissions can be changed later from its edit page, and switching it to Full access or back is the same screen. Renaming, disabling and deleting a key work whatever its permissions are.

A limited key stays in its own workspace. It is pinned to the workspace it was created in, on both the REST and GraphQL APIs. On GraphQL, an organisationId for any other workspace is refused: reports and enhancements return an error ("User is not a member of organisation") and seriesList returns an empty list. The key can't see or act on your account's other workspaces.

A limited key can never reach billing and subscriptions, changing plans, team members and roles, API key management, your account's details, or the standards editor. On GraphQL these operations are refused before they run, and the account and billing fields that remain on shared types, such as an organisation's role, payments, subscription, plan and limits, come back null. A limited key also can't change which people are on a podcast (seriesNotifications and podcastNotifications refuse setMembers and removeUserIds), though it can still set its own email preferences through those fields, which needs Edit show settings (series.edit).

What a refusal looks like. On the REST API it is a 403 with the code forbidden and a message naming the endpoint, such as This API key's permissions do not cover POST /api/rest/v1/reports. On GraphQL it is an entry in the errors array reading This API key's permissions do not cover followed by the field, such as changePlan. Nothing was created and nothing was charged. Edit the key to add the permission, or use another key.

Keys held by Audio Audit staff carry separate staff permissions, are not created through this page and show as "Managed by Audio Audit staff".

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, a personal key can fetch the account it 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 your own account. An Organisation key is refused on user, because it reaches its Organisation and not the owner's account: test it with currentApiKey instead, whose owner is the Organisation (see Workspaces).

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