API keys

An API key lets your code do what you do in the console — create, update and delete records, add fields, and drive the rest of the admin API — without a person signing in. Every integration you build (a CI job, a sync script, a back-office tool) authenticates with a key. Give each one its own key: then you can see which integration did what, and revoke one without disturbing the others.

Auto-plays · use Back / Next to step through at your own pace.

Create a key

1. Go to Developers → API Keys and click Create API Key.
2. Give it a name that says what it’s for — ci-deploy, catalogue-sync.
3. Pick its scope — the whole account, a single list, or a single group (below). Optionally set an expiry date and pick the permissions it should have (below).
4. Click Create. The key’s secret is shown once — copy it now and store it somewhere safe. It is never shown again.

Scope: account, list or group

A key has two independent dials — scope (where it can reach) and permissions (what it can do there):

• Whole account (default) — reaches every list and group, like your console session. Right for back-office tools and CI.
• A single list — confined to one list; it can never touch any other list, any group, or your account settings.
• A single group — confined to one group and its member lists.

For a browser embed (autocomplete, a public search box) create a list-scoped, read-only key: scope it to the one list and give it read-only permission. Because it ships in your page’s JavaScript, this is the safe choice — if it’s copied out it grants nothing but searching that one list, and putting a different list name in the URL just returns 403. The scope also sets the key’s region prefix (ssk_us_…), which routes requests to the right regional API. A list- or group-scoped key takes its region from the scoped resource; a whole-account key defaults to your account’s home region but offers a Region dropdown to override it (the choices are the regions with an API deployment). It’s only a routing hint — an account key still works everywhere, so a “wrong” choice just means a slower cross-region hop, never a broken key.

Permissions: just what it needs

The permissions picker is grouped by area — account, analytics, API keys, records, fields, evals, media and more. The rule of thumb is least privilege: give a key only the operations its integration actually performs.

• Leave it empty and the key is granted all permissions — convenient for a trusted back-office tool, risky for anything exposed.
• Tick a few and the key can do only those things. A key that only ingests records needs record-write permissions and nothing else — if it leaks, it can’t delete your lists or read your account.

Keys work on the data-plane API. If a request comes back 403 where you expected success, the key is almost always missing the permission for that operation — add it and re-issue, or use a key with all permissions to confirm.

Expiry, rotation and revocation

• Expiry — set a date and the key stops working after it, on its own. Good for temporary access (a migration, a contractor) you might otherwise forget to clean up.
• Rotation — when a key ages out or you simply want fresh credentials, create a new one, switch your integration over, then delete the old — no downtime, because the two coexist during the swap.
• Revocation — delete a key and it stops working immediately. If a secret leaks, this is the fix, and because each integration has its own key, only that one needs a new value.

A worked example

Your deploy pipeline needs to push the latest catalogue into a products list on every release. You create a key named ci-deploy, scope it to the products list, give it just the record-write permissions (no account read, no key management), and set it to expire at the end of the quarter. The two dials do different jobs: the list scope means the key literally cannot reach any other list, group or your account settings; the permissions mean that even on products it can only write records, not delete the list or read analytics. So if the CI system is ever compromised, the blast radius is a single list’s records. At quarter’s end you rotate it in a minute: new key, update the pipeline secret, delete the old one.