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_idthat another site of your organisation uses answers 409conflict, 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.
| Permission | On the API keys page |
|---|---|
sites:read | View sites |
sites:write | Add and change sites |
sites:delete | Delete sites |
banner:read | View banner settings, texts, regions and cookies |
banner:write | Change banner settings, texts, regions and cookies |
accessibility:read | View the accessibility widget |
accessibility:write | Change the accessibility widget |
scans:read | View scans |
scans:write | Start scans |
consent:read | View consent records and statistics |
webhooks:read | View webhooks |
webhooks:write | Add and change webhooks |
reports:read | View 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:
- On the API keys page, select Roll key beside the key.
- 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.
- 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.
- 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'sfeaturenames what, and itsdetailsays 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 norequired_scope. - 429
rate_limitedin 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.
