> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/dispatch/use-dispatch/api-keys.md). # 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. {% hint style="info" %} **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. {% endhint %} ## 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](/dispatch/manage/manage/guardrails.md). 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](/dispatch/manage/users.md). ## Creating a Key {% stepper %} {% step %} **Open the form** On **API keys**, click **Create key**. The **New API key** panel opens. {% endstep %} {% step %} **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. {% endstep %} {% step %} **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. {% endstep %} {% step %} **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**. {% endstep %} {% endstepper %} {% hint style="warning" %} **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. {% endhint %} 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. {% hint style="info" %} **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. {% endhint %} ## 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](/dispatch/manage/manage/tags.md) 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](/dispatch/use-dispatch/cookbooks.md) | | Make a first request end to end | [Quickstart](/dispatch/get-started/quickstart.md) | | Set defaults and limits for everyone | [Users](/dispatch/manage/users.md) | | Define the tags keys can carry | [Tags](/dispatch/manage/manage/tags.md) | | Report spend by owner or tag | [Cost Reporting](/dispatch/cost-and-insights/cost-reporting.md) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.darcyiq.com/dispatch/use-dispatch/api-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.