Create an API key safely

Create it

Keys live under API in the dashboard, on the screen titled API & integrations. You need to be an owner or an admin of the workspace · a member sees the list and a note reading "Only an owner or admin can create or revoke keys".

1. Open the create form. On API, under API keys, press Create key. A dialog opens with four fields and no key yet · nothing is minted until you submit it.
2. Name it after the thing that will hold it. The first field is a name, up to 64 characters, and the placeholder shows the shape to copy: production-server. When a key has to be revoked in a hurry, this name is what tells you what you are about to break.
3. Choose Access. Two options: Read only and Read and write. Read only is preselected and is the right answer for dashboards, exports and monitoring. Pick write only if this integration has to create or change codes · a write key can repoint a printed one.
4. Choose Expires. In 30 days, In 90 days, In 365 days or Never. An expiry date turns rotation into a schedule instead of a resolution. Expiry is checked on every request, so it takes effect at the minute it says it will.
5. Set a Daily credit budget. A whole number of credits between 1 and 1,000,000, or leave it empty for no limit. This is the field that turns handing a key to a script or an agent into a bounded decision. Pick a number the integration's normal day fits inside with room to spare.
6. Press Create, then copy the key. The dialog replaces the form with the full key and the notice "Copy this key now. It will not be shown again." It starts with tr_. Paste it into your secret store before you close the dialog.

The new row appears in the API keys table showing its name, its first eight characters, its access badge, Spend today against its budget, and when it was last used. Send the key as Authorization: Bearer tr_... · the same header the API and MCP reference uses throughout.

Choosing the scope

There are two values rather than a permission matrix, and the question they answer is whether this credential can change the physical world. A code on a printed menu is a physical object; a write key can send it somewhere else.

• Read only · listing codes, reading scan counts, exporting analytics. It cannot reach anything that spends credits, and the billable operations are not in the list a connected agent is given, so there is nothing to talk it past.
• Read and write · creating codes, editing destinations, writing routing flows, publishing pages. Write implies read. This is the scope that needs a budget on it.
• When in doubt, read. Replacing a read key with a write key later is a five-minute job. Finding out that a key which turned out to be write-scoped was pasted into a public repository is not.

The daily budget, precisely

The budget is a ceiling on credits spent per UTC day by this key, enforced at the single point where the wallet is debited. Every billable operation passes through it, present and future, so nothing has to be remembered per feature.

• Enforced before the spend, not reported after it. A key that has spent its ceiling stops there, whatever the workspace balance holds.
• It resets at UTC midnight, not at your local midnight. Worth knowing before you size it against a nightly job.
• A refund goes back to the budget too. Work that failed and was refunded does not eat the key's allowance for the rest of the day.
• You can watch it. The keys table has a Spend today column reading spent / budget for a budgeted key. It is how an owner notices a runaway integration before the wallet does.

Where the key lives after this

The natural first move · paste the key into a config file and commit it · puts a spending credential in git history, where it stays after you delete the line. Two habits avoid it:

• Read it from the environment. Keep the key in your secret store and have the config name a variable rather than carry the value. The MCP setup guide shows the shape for each assistant, including the ones that can prompt for the key and remember it instead of writing it into a file.
• One key per consumer. A key per server, per script, per agent. Shared keys cannot be revoked without a meeting, and Spend today tells you nothing when four things share a row.
• Set an expiry on anything you hand to someone else. A key with no expiry is a key nobody will ever get round to rotating.

Rotating and revoking

Because a key's power is fixed at creation, rotation is the only edit there is. It is the same three moves whether you are changing a scope, raising a budget or responding to a leak.

1. Create the replacement first, with the access and budget you now want, and a name that says which one it is.
2. Move the integration across and confirm it works. Both keys are live at this point, which is the whole reason for doing it in this order.
3. Revoke the old key. Press Revoke on its row. The confirmation names what it breaks: "Any integration still authenticating as ... breaks immediately". It is instant and cannot be undone.

Both create and revoke are written to the workspace history with the key's name and its display prefix, never the key itself · so "when did this credential appear" has an answer during an incident.

When a call is refused

• 401 · the key is missing, unknown, or expired. An expired key is not treated as a key at all, so this is what a lapsed rotation looks like from the client side.
• 402, naming the budget · this key hit its daily ceiling. It resets at UTC midnight. Raising the ceiling means a new key, so the practical fix in the moment is to wait or to run the work with a key sized for it.
• 402, naming the balance · the workspace is out of credits. That one is fixed under Billing, by a person. The two 402s are deliberately distinguishable, because sending someone to buy credits they already hold wastes the trip.
• 429 · an hourly ceiling per credential, split between reads and writes and scaling with the credit packs the workspace has bought. The message states the seconds until reset, so the correct response is to wait that long rather than retry immediately.
• 403, owner or admin role required · minting and revoking keys are both gated on role. A member sees the list without the buttons; ask an owner or an admin to mint the key.

Questions

Can I change an API key’s permissions later?

No. Access, expiry and the daily credit budget are fixed when the key is created. There is no edit form and no endpoint behind one. To change any of the three, revoke the key and create a replacement, which means updating whatever was authenticating with the old one.

I lost the key. Can I see it again?

No. Only a SHA-256 hash of the key is stored, so nothing on our side can reproduce it. The list shows the first eight characters so you can tell your keys apart. If you did not copy it, revoke that key and create another.

What scope should I choose?

Read only, unless the integration has to create or change something. A read key can list your codes and count your scans and cannot repoint a single printed one. That covers dashboards, exports and monitoring, which is most of what people build.

What stops a runaway script from spending my whole balance?

A daily credit budget on the key. It is checked at the moment the wallet is debited rather than reconciled afterwards, so a key that has spent its ceiling stops there whatever the balance holds. It resets at UTC midnight, and a refund for work that failed is handed back to the budget as well as the wallet.

Who can create an API key?

An owner or an admin of the workspace. A member sees the keys but not the buttons, with a line saying why. Creating and revoking are both gated, because revoking is instant and breaks whatever was authenticating with the key.

Can an AI agent create a key for itself?

No. Key creation is dashboard-only and is deliberately absent from both the API and the MCP server. A credential that can mint further credentials is not a credential you can bound.