Skip to documentation content
CookieBeam

Manage API keys

Create, restrict, rotate and revoke the API keys your team uses for the CookieBeam API and the mobile SDKs.

API keys let your own systems call the CookieBeam API, for example to record consent from a mobile app or to read banners from a script. This page covers managing keys. For how requests are authenticated, the key format and every scope, see Authentication.

Who can manage keys

  • Only the team owner can create, rotate and revoke keys. API keys in the sidebar is only shown to owners.
  • API access is part of the Professional plan and above. On other plans the page says API access needs a Professional plan or above, and API requests made with an existing key are refused.

Create a key

  1. Open API keys.
  2. Enter a name that says where the key is used, for example "Android app" or "Reporting job".
  3. Choose live or test. Test keys are read-only.
  4. Choose the scopes the key needs. You can only grant scopes that your own permissions allow, and scopes marked reserved cannot be added because no endpoint uses them yet.
  5. Optionally limit the key to specific banners or environments.
  6. Choose how long the key is valid: from 1 to 365 days. Live keys default to 90 days and test keys to 30 days.
  7. Create the key and copy it. The full key is shown only once. CookieBeam stores a hash, so a lost key cannot be shown again.

A team can have at most 20 active keys.

Good practice

  • Create one key per system, with only the scopes that system uses. A key can then be revoked without affecting anything else.
  • For a mobile app, use a key with only the consent:write scope. A key built into an app can be extracted from it.
  • Keys act as the team, not as the person who created them. Banner access limits on team members do not apply to a key, so use the key's own banner restrictions where you need them.
  • Store keys in a secrets manager, not in source code.

Rotate, restrict or revoke

  • Rotate creates a replacement key with the same name, scopes and restrictions and a new expiry date, and revokes the old key at the same moment. Have the new value ready to deploy before you rotate.
  • Restrictions can be changed later without changing the secret or the scopes.
  • Revoke stops the key working straight away. Revoking cannot be undone; create a new key instead.

Creating, rotating and revoking keys is recorded in the team's audit trail.

Related