Keys - Check That Field

Partners’ keys are made by hand on the Keys tab of the admin page (/admin#keys). There is no self-service sign-up, and billing is by arrangement, invoiced by hand. There are two kinds:

Kind	Starts with	For	Tied to sites
API (secret)	`ctf_sk_live_`	A partner’s server, sent as `Authorization: Bearer …`	No
Widget (publishable)	`ctf_pk_live_`	The widget, in a partner’s web pages	Yes, at least one

A partner who wants both needs two keys. Each key has its own monthly quota.

Issue a key

Get what you need from the partner

Their company name, what they’re building, roughly how many calls a month they expect, and, for the widget, every site it will be on.

Make the key

Open the Keys tab and choose New key. Pick API or Widget, then fill in:

Name: what the key is for, such as “Production” or “Lettings site”. Up to 120 characters.
Customer: who it belongs to, such as “Smith & Co Estate Agents”. Up to 200 characters.
Sites (Widget only): the domains, separated by commas or spaces, such as smithandco.co.uk, homes.example.org. Each covers its subdomains, so smithandco.co.uk covers www.smithandco.co.uk too. You can paste full addresses: https:// and any path are dropped. Add localhost if they want to test on their own machine.
Calls a month: the quota, from 1 to 100,000,000. It starts at 10,000. For the widget, each load is one call.

Choose Make key.

Copy the key now

The next screen shows the key, with a copy button. This is the only time it is shown: we keep only a fingerprint of it. The screen closes only from its Done button, so you can’t lose it by clicking away.

Send it to the partner

API key: send it privately, not in a shared channel. Tell them to keep it on their server, and point them to Authentication and Quotas and limits.
Widget key: it ends up in public HTML anyway, so ordinary email is fine. Send the snippet with their key filled in, the list of sites it works on, and a link to Install the widget.

In both cases, tell them their monthly quota.

Sites can’t be shared endings such as com, co.uk, org.uk, gov.uk, io or london: a key for those would work on everyone’s site. The form says “Not a site’s domain” for those. A widget key needs at least one site, and an API key takes none.

Read usage

The table lists every key, live ones first, newest first. Usage is for this calendar month (UTC), and quotas reset on the 1st.

Column	What it shows
Key	Name, customer and the key’s first 16 characters, enough to match it to what a partner sends you.
Kind	API (secret) or Widget (publishable), and “Revoked” with a date.
Sites	A widget key’s domains.
Used this month	Calls counted this month, of the quota. Failed API calls aren’t counted.
Views	Widget views this month: loads where enough of the widget was on screen.
Clicks	Widget clicks this month on the link to the full report or the map.
Last used	The last day the key made a call, or “Never”.

When Used this month reaches the quota, the partner’s calls get 429 quota_exceeded and their widget says it will be back on the 1st. There’s no way to change a key’s quota or sites after it is made: issue a new key and revoke the old one once the partner has switched.

Views far below Used this month for a widget key usually means the widget sits low on long pages that readers don’t scroll to. That’s normal: the widget is loaded as it nears the screen, but a view needs it to be seen.

Revoke a key

Choose Revoke on the key’s row and confirm. The partner’s API calls are refused (403 key_revoked) or their widget stops showing, at once. This can’t be undone: they would need a new key. Revoked keys stay in the table, greyed out, so their history isn’t lost. Revoke a key when:

a secret key has been exposed, for example in a web page or a public repository;
a partner leaves or stops paying;
you have issued a replacement with different sites or a different quota.