A Key That Can Only Read

In March the finance team connects a dashboard tool to the operations system. Somebody issues an API key, pastes it into the dashboard’s connection screen, and the monthly sales and purchasing charts start drawing themselves. Four people in the dashboard tool can see that connection. One of them is a contractor. Nobody thinks about the key again, because nothing about it has ever gone wrong.

In October procurement wants their supplier onboarding form to create vendor records automatically. IT is asked how long that will take, and someone in the meeting says the obvious thing: there is already a key, it already works, just tick the box that lets it write.

Ticking the box takes ten seconds and quietly hands every holder of the dashboard’s key, the contractor included, the ability to change your supplier list. Nobody decided that. It fell out of a convenient shape.

Where a key actually lives

A user account belongs to a person who can be asked questions, trained and offboarded. An API key belongs to a system, and systems are leaky in ways people are not. A key gets copied into an environment file, a no-code tool’s settings, a script on a server nobody owns any more, a support-ticket screenshot, an old agency’s password vault. Every one of those copies holds exactly the power the key holds, for as long as the key is alive.

So the useful question about a key is not “do we trust the integration?” but “what happens on the day a copy of this string is in the wrong hands?” And the answer to that depends almost entirely on whether the key can write.

The asymmetry is the whole argument. Most integrations only ever read: a dashboard, a website stock feed, a nightly extract into a warehouse. They are also the ones most likely to be configured once in a hurry and left alone for years. Giving them write power buys nothing and costs the right-hand column.

Why a checkbox on one key is the wrong shape

There are two ways to give an integration write access. You can make writing a property of a key that already exists, a toggle somebody can flip. Or you can make it a separate, named scope that a key either was issued with or was not. They sound like the same feature. They behave very differently once keys are out in the world.

A toggle widens a credential that has already been distributed. Every copy of the string, everywhere it was pasted, gains the new power at the same instant, and the person flipping the toggle has no way to know where those copies are. A separate scope means a separate key: a new string, issued to one system, named after it, carrying a decision somebody made on the day it was issued. The old reading key stays exactly as weak as it was.

Widening a key you already handed out widens every copy of it at once. Issuing a second key widens nothing.

This is least privilege applied to machines. The difference from people is that a machine never complains about being under-privileged, so the only pressure in the system pushes towards more access, and the shape of the credential has to push back.

How the line is drawn here

The developer API keys are issued in Settings → Webhooks & API by someone holding the permission to manage API keys. Each key carries your organization with it, so no request ever names a workspace; that half of the design is covered in No Route Here Asks Who You Are Asking About. This post is about the other half: what a key is allowed to do once it is in.

Four rules sit underneath that table, and they are enforced in the one place every request passes through rather than in each endpoint:

• Nothing read-flavoured satisfies a write. The read umbrella reaches every read endpoint and none of the write ones. A request to create an item with a reading key is refused with a 403 that says the scope is insufficient and names the scope it would need.
• A module’s write scope reads that module and nothing else. A key issued for procurement:write can read the vendor it just created; it cannot list your customers. The supplier sync gets suppliers.
• A key with no scopes is refused, not treated as all-access. An empty list is the most common way a permission system fails open, because “no restrictions recorded” reads the same as “no restrictions”. Here it reads as no access.
• Scopes are fixed at issue. There is no screen that edits the scopes on a live key. More power means a new key, which is a visible event with a name and a date on it.

The last rule feels like friction, and it is meant to. Narrowing is cheap: issue a narrower key, move the integration across, revoke the old. Widening is the dangerous direction, so it is an act of issuing rather than an edit.

A key does not grow when the product does

The developer API began as reads only. Master-data writes arrived in October 2026, and that created a question most API designs answer by accident: what happens to the keys that already exist?

Some of those keys had been issued with the read umbrella, and a few internal ones with a bare *, which in plain English means “everything”. On the day writes shipped, “everything” could have started to include writing. Every one had been pasted somewhere on the understanding that it could look and not touch, and that would have become false overnight with nobody told.

So it does not. Both * and the read umbrella satisfy read scopes only, and writes need a scope that names writing. A test pins it: the umbrella, the wildcard and a single-module read key are each refused on create, and no item exists afterwards.

Write is itself narrow

Holding a write scope does not mean a key can do what a person in the product can do. The writes reach master data, the reference records everything else hangs from, and stop there: create and update for items, customers and vendors. There is no delete over the API. A few fields are refused outright with a 422 that names them, even to a key holding the write umbrella:

• An item’s stock. A new item starts at zero, and stock moves only through adjustments in the product, where counts, reasons and approvals apply.
• A supplier’s payout details. Bank account and mobile-money payout fields are changed in the product, where a second person can be required and the supplier is told. An integration that could rewrite where a supplier is paid would be the most valuable string in your organization.
• An item’s type and inventory account after creation. Switching an item between stock and service moves it in or out of every stock path at once, so it is settable on the way in and nowhere else.

The reason is that an API key has no person behind it. Approval controls work by separating the person who asks from the person who agrees, and a key cannot be separated from itself. So anything that moves stock, money or an approval stays where a person does it.

One thing to know, because it is a reason to keep inventory:write rare. In the product, changing an item’s SKU or category is a critical-field change: someone without the approval permission raises a request rather than making the change. An item update through the API applies a new SKU or category directly. Treat a key with inventory:write the way you would treat a person who holds that approval permission, because in effect it does.

Which key each integration should hold

Running the keys once they exist

1. The token is shown once

   At creation the full key is displayed once and then only a short prefix is kept readable; the stored copy is a hash. If it was not saved, issue a new one rather than looking for the old.

2. Expiry is optional and worth setting

   Anything from one day to two years. A key with an expiry is a key somebody has to think about again, which is the point.

3. Last used tells you what is dead

   The key list shows when each key last made a call, stamped at most once a minute. A key reading “Never” a month after issue, or last used in spring, is a key to revoke.

4. Rotation keeps the scopes

   Rotating revokes the old token immediately and issues a new one with the same scopes and remaining expiry. That makes it the right tool for a suspected leak and the wrong one for narrowing a key; to narrow, issue a fresh key with fewer scopes and revoke the old.

5. Every write is attributed to the key

   Creates and updates land in the audit log against “API key” plus the key’s name, with the fields an update changed. Name keys after the system holding them, not after the person who issued them.

6. A key can check itself

   The /me endpoint answers with the organization, the key’s name, prefix, scopes and expiry, for any usable key whatever its scopes. It is the first call an integrator should make, and the quickest way to confirm a key is as narrow as you think.

A create also honours an Idempotency-Key header for twenty-four hours, so a sync that retries after a timeout gets the first result back rather than a second customer; the same header with a different body is refused with a 409. Why that window and that refusal are the right behaviour is argued in The Second Identical Request.

For when to build on the developer API at all, read The REST API: Tokens, Permissions and Limits. The scope list and error codes are in the API reference, and the setup walkthrough is in the developer API guide.

Frequently asked questions