> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkthatfield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keys

> Issue, send, monitor and revoke partners' keys for the API and the widget.

Partners' keys are made by hand on the **Keys** tab of the admin page ([/admin#keys](https://www.checkthatfield.com/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](https://docs.checkthatfield.com/widget/overview.md), 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

**1. 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.

**2. 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**.

**3. 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.

**4. 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](https://docs.checkthatfield.com/api/authentication.md) and [Quotas and limits](https://docs.checkthatfield.com/api/quotas-and-limits.md).
* **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](https://docs.checkthatfield.com/widget/install.md).

In both cases, tell them their monthly quota.

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.