Skip to content
Start free Sign in

API keys and permissions

Agency plan

Last updated

Available on the Agency plan

This feature is included in the Agency plan and the plans above it. See pricing

An API key lets your software call the Kukie.io API for your organisation. A key belongs to the organisation, not to a person, so it keeps working when the person who created it leaves. It can do only what you choose when you create it.

The API is included on the Agency and Unlimited plans. See the pricing page for what each plan includes.

What a key looks like

A key starts with kk_live_. Treat it as one opaque string of up to 128 characters, and do not rely on its length or its parts. Kukie.io shows a key only once, when you create or roll it, and stores no copy you can read later. The API keys page shows the last four characters, so you can tell keys apart.

Send the key in the Authorization header:

Authorization: Bearer kk_live_...

Never put a key in a URL. A request with a key in its query string answers 400 credential_in_query, and you should roll that key, because addresses are kept in logs and browser history.

Who can create a key

  • Owners and admins of the organisation. Editors cannot create, roll or revoke keys.
  • The organisation's plan includes the API, and the organisation is not on a free trial.
  • You confirm with your password, unless you confirmed it a short time ago, and, if your account uses two-factor authentication, with a code from your authenticator app. A recovery code does not work here.
  • You accept the API Terms each time you create or roll a key.

You can create a key while your organisation has fewer than 25 keys that still work. Keys in the grace period after a roll count too. With them an organisation can hold up to 50 keys that still work: a roll with a grace period is refused at 50, and a roll with no grace period is not. In any 24 hours an organisation can create 50 keys and roll 50.

Owners and admins get an email whenever a key is created or rolled.

Which sites a key reaches

Under Sites you choose one of two options:

  • All sites, including sites added later. Only such a key can create a site.
  • Only the sites you choose. For every other site the API answers as if the site did not exist: 404 when the site is in the address, and 422 when the request body names it. One exception: an external_id that another site of your organisation uses answers 409 conflict, whether or not the key reaches that site.

Permissions

Each operation in the API reference names the permission it needs. A key without it gets 403 insufficient_scope, and the answer's required_scope names the permission that is missing.

PermissionOn the API keys page
sites:readView sites
sites:writeAdd and change sites
sites:deleteDelete sites
banner:readView banner settings, texts, regions and cookies
banner:writeChange banner settings, texts, regions and cookies
accessibility:readView the accessibility widget
accessibility:writeChange the accessibility widget
scans:readView scans
scans:writeStart scans
consent:readView consent records and statistics
webhooks:readView webhooks
webhooks:writeAdd and change webhooks
reports:readView scan reports

A permission that ends in :write includes the matching :read, and sites:delete includes sites:read. Nothing else is included. Reading the account and your API usage needs no permission.

Under What the key can do you choose a ready-made set or Custom. For a key that reaches all sites the sets are:

  • Full integration: accessibility:read, accessibility:write, banner:read, banner:write, consent:read, reports:read, scans:read, scans:write, sites:read, sites:write, webhooks:read, webhooks:write.
  • Site provisioning: banner:read, banner:write, scans:read, scans:write, sites:read, sites:write.
  • Read only: accessibility:read, banner:read, consent:read, reports:read, scans:read, sites:read, webhooks:read.

No set includes sites:delete. Add it under Custom only for software that must delete sites, because deleting a site also deletes its consent records. The two webhooks permissions are for webhooks. A key for chosen sites cannot have them.

A key never gains a permission later. To change what a key can do, create a new key.

Expiry and reminders

Every key expires. Under Expires after you choose 30, 90, 180 or 365 days, and 180 days is the default. Owners and admins get a reminder by email 14 days and 3 days before a key expires, unless the key has already been rolled. The reminders go only while your organisation's plan includes the API and the API is switched on, and never for a key for chosen sites that no longer reaches any site.

Roll a key

Rolling replaces a key with a new one that has the same name, permissions and sites. To change your software without downtime:

  1. On the API keys page, select Roll key beside the key.
  2. Choose a Grace period of up to 7 days. The current key keeps working for that time, or until its own expiry date if that comes sooner.
  3. Select the checkbox I accept the API Terms. Enter your password if the dialog asks for it, and your authentication code if your account uses two-factor authentication. Select Roll key, then copy the new key.
  4. Put the new key into your software before the grace period ends.

A rolled key starts fresh with idempotency keys and list cursors: a cursor or an Idempotency-Key used with the old key means nothing to the new one.

Revoke a key

On the API keys page, select Revoke key beside the key and confirm. A revoked key stops working at once and cannot be restored. Revoke a key as soon as you think it has been exposed.

When a key is refused

  • 401 unauthenticated: the key is missing, mistyped, unknown, expired or revoked. The answer is the same in every case and does not say which.
  • 403 plan_upgrade_required: the organisation's plan does not include the API, or does not allow what the request asks for. The answer's feature names what, and its detail says what to do. Reading the account still works when the plan does not include the API, so your software can see why, and so does deleting a webhook endpoint.
  • 403 insufficient_scope: the key lacks the permission the operation needs, or it reaches chosen sites and the operation needs a key for all sites. In the second case the answer has no required_scope.
  • 429 rate_limited in place of the 401: after 20 refused keys in a minute from one address (an IPv6 address counts with its /64 network), a further request with a refused key answers 429 until that minute ends. A key that works is never refused this way. Waiting does not make a refused key work, so check the key first.
Was this helpful?

Listed on