API keys

A credential for a machine. Issued by a signed-in person, scoped to one workspace, and able to reach exactly two paths.

Owners only

Every endpoint on this page needs the owner role. A key acts for the whole workspace, so issuing one is an owner's decision.

Issue one

POST /v1/api-keys

{ "name": "orders-service" }

Name it after the system that will use it. The name is what you read when deciding whether revoking it breaks anything, and key 1 answers that question badly at the worst moment.

The key is returned once and never again

It is stored as a SHA-256 hash. No endpoint can return it, because nothing has it — put it straight into your secret store.

SHA-256 rather than bcrypt, and that is deliberate rather than weaker: bcrypt salts every row, so a hash could not be looked up and verifying a key would mean comparing against every key in the system on every request. A key is high-entropy random data, not a human-chosen password, so the slow hashing that protects passwords buys nothing.

List them

GET /v1/api-keys

Name, prefix, created, revoked, and last used. That last field is the one to look at: a key with a lastUsedAt you cannot account for is a key to revoke now and investigate afterwards. A key that has never been used is one you can revoke without thinking.

Revoke

DELETE /v1/api-keys/{id}

Immediate, with no grace period. Rotating means issue, deploy, then revoke — in the other order every call fails until the deploy lands.

What a key can reach

/v1/events      and everything under it
/v1/customers   and everything under it

Anything else is 403. Connecting a channel, writing workflows, reading conversations and replying to a customer are things a signed-in person does — see Authentication for why the surface is this narrow.

Errors →

One envelope, every code, and what to do about each.