API Keys

Create, copy, pause, tag and revoke Dispatch API keys, and how every key shares its owner's allowance

An API key is what your tools send with every request so Dispatch knows who is calling. This page is where keys are created, paused, tagged and revoked. A Dispatch User sees and manages their own keys. A Dispatch Admin sees every key in the organization and can create keys for other people, services and jobs.

Keys are cheap to make on purpose. Spend limits and content policy belong to the key's owner, not to the key, so you can give each laptop, project or pipeline its own key without changing what anyone may spend.

One allowance, any number of keys. Every key an owner holds draws on the same allowance. Creating another key never adds to it, and revoking one never takes from it.

Keys and Their Owners

Every key has a Key owner. Usually that's a person, but it can also be a service or a job, such as a nightly pipeline. The owner carries:

• A spend limit, which can reset daily, weekly or monthly, or apply once in total. An owner can also have no limit of their own, in which case only the organization's budget applies.

• A guardrail, the content policy applied to their requests. See Guardrails.

Each key carries only its own label, its own on/off switch, its own tags and its own spend figure.

The first key an owner receives sets them up with your organization's defaults for a teammate's allowance and guardrail. Changing those defaults later doesn't change owners who already have keys. See Users.

Creating a Key

1

Open the form On API keys, click Create key. The New API key panel opens.

2

Name it Enter a Label. Name the key after where it will live, such as "My laptop" or "Production pipeline", so you can tell your keys apart later. A label is required.

3

Choose the owner (Dispatch Admins) The Key owner starts as you. To issue the key to someone else, open the picker and choose an existing key owner, choose a colleague from your organization, or type a name and choose Add to create an owner for a service or job. Under the picker, Dispatch tells you what the key will spend against. Dispatch Users don't see this field, because their keys are always their own.

4

Create and copy Click Create key. The Key created dialog shows the full key, which starts with dr_live_. Use the copy button, then click Done.

The key is shown once. Dispatch can't show it again after you close the Key created dialog. If you lose a key, revoke it and create a new one.

The dialog also confirms what the new key spends, for example a monthly amount and the guardrail it's under, shared with every other key its owner holds.

Give automated jobs their own owner. The budget belongs to the owner, so a key for a nightly job owned by whoever set it up spends from that person's allowance. Owning the key by the job keeps the two apart.

The Key List

Revoked keys are removed from the list. Each owner's keys are grouped together, and anything that belongs to the owner rather than the key is shown once, on the owner's first row.

Column	What it shows	Who sees it
Key	The label, and the key's first characters and last four, such as dr_live_•••a1b2	Everyone
Key owner	The owner's name and email, and "N keys, one budget" when they hold more than one	Dispatch Admins
Spend (30 days)	What this key has spent over the last 30 days. A dash means the figure couldn't be read, not that nothing was spent.	Everyone
Tags	The key's tags, with Add or Edit	Everyone
Owner budget	Spent so far against the owner's limit and reset period, or "no limit", with a progress bar and Change budget	Dispatch Admins
Guardrail	The owner's guardrail, or "None"	Dispatch Admins
Active	The switch that pauses and resumes the key	Everyone

Dispatch Users see their own allowance above the list instead, for example "$120 of $500 per month spent", with the reminder that it's shared across every key below.

When you follow a link to a key or a person from another page, such as Insights, their rows are highlighted and scrolled into view.

Pausing a Key

Turn off the Active switch to pause a key. The pause takes effect on the key's next request, and the owner's other keys keep working. Turn the switch back on to resume it. Pausing is the right choice when you only need to stop a key for a while, because revoking can't be undone.

Revoking a Key

Click the trash icon at the end of a key's row, then confirm with Revoke. As the confirmation says, the key stops working immediately and can't be restored. The owner's other keys and their budget are unaffected.

Replacing a Key

There is no separate rotate action. To replace a key, for example after it was exposed or lost:

1. Create a new key for the same owner.

2. Put the new key into your tools.

3. Revoke the old key.

The new key spends from the same allowance as the old one.

A key marked Needs replacing was issued in a way current Dispatch can't use, so it can't make requests. Revoke it and create a new one.

Changing an Owner's Budget (Dispatch Admins)

Click Change budget on an owner's row to open Budget for that owner. It applies to every key they hold, now and later.

Field	What it does
Spend limit (USD)	The most this owner may spend. Leave it empty to lift the cap entirely. It must be greater than zero when set.
Resets	Never, daily, weekly or monthly. Never makes the limit a total rather than a recurring allowance.
Guardrail	None, or one of your organization's guardrails. Each owner has one policy.

Changes take effect on the next request. Spend against the limit is measured every few minutes, so an owner can overshoot a limit slightly before Dispatch refuses them.

Tagging Keys

Tags say what a key is for, such as a team, client or project, so spend can be grouped by them in Cost Reporting. Your Dispatch Admin defines the tags. Both roles can put them on keys.

Click Add or Edit in a key's Tags column to open Tags for that key. Tick the tags that apply and click Save. The tags apply to this key only, not to the owner's other keys.

• A key can carry up to 10 tags, plus up to 5 tags that choose between values.

• Tags marked automatic aren't stamped on every request. Dispatch works them out for each new conversation the key starts, and they only land where they fit. A tag that chooses between values shows its options as "One of: ...".

• A tag that comes from the owner's guardrail is shown ticked and locked, marked "from" the guardrail, and appears with a dashed outline in the list. Change the guardrail to remove it.

• A tag applies from the moment it's added. Spend that's already been recorded keeps the tags its key had at the time.

Dispatch Admins can also tag many keys at once. Tick the keys in the list, choose a tag from Choose a tag, then click Add tag or Remove tag. Clear selection unticks everything.

See Tags for how tags are defined.

What Each Role Can Do

Action	Dispatch User	Dispatch Admin
See keys	Their own	Every key in the organization
Create keys	For themselves	For anyone, or for a service or job
Pause, resume and revoke keys	Their own	Any
Add and remove tags	On their own keys	On any key, including in bulk
Change an owner's budget and guardrail	—	✓

Next Steps

Goal	Documentation
Use your new key in a tool	Cookbooks
Make a first request end to end	Quickstart
Set defaults and limits for everyone	Users
Define the tags keys can carry	Tags
Report spend by owner or tag	Cost Reporting