> ## Documentation Index > Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt > Use this file to discover all available pages before exploring further. # Managing LLM API Keys > Set expirations on LLM Gateway API keys, rotate them without an outage, extend them, filter and act on them in bulk, and limit how long users' own keys may live. ## Overview Every request to the LLM Gateway carries a `bd-…` API key. Keys can expire, and they can be rotated, extended, disabled, and revoked. Admins can also limit how long the keys users create for themselves may live. | Where | Who | What you can do | | - | - | - | | **LLM Management → API Keys** | Admins | Every key in the organization: create, rotate, change expiration, disable, enable, revoke, and act on many keys at once | | **LLM Management → Key Policies** | Admins | The organization's limit on how long self-serve keys may live, with group and user overrides | | [**Settings → My Models → API Keys**](https://app.barndoor.ai/settings/models?section=api-keys) | Every user | Your own keys: create, rotate, disable, enable, and revoke | ## Before You Begin You'll need: * A Barndoor account. Any user can manage their own keys; **LLM Management** needs **admin privileges**. * The LLM Gateway set up for your organization — see the [LLM Gateway Quickstart](https://docs.barndoor.ai/how-tos/llm-gateway-quickstart.md). ## Key Status Each key is in exactly one status. The **Status** column shows it, and the gateway enforces it on every request. | Status | Requests | What it means | | - | - | - | | **Active** | Accepted | The key works and isn't due to expire within 7 days | | **Expiring soon** | Accepted | The key expires within 7 days. The **Expires** column shows how long is left. | | **Disabled** | Rejected | An admin or the owner turned the key off. **Enable** turns it back on with the same secret. | | **Expired** | Rejected | The expiration has passed. Rotate the key, or have an admin change its expiration, to bring it back. | | **Revoked** | Rejected | Permanently off. A revoked key can't be brought back. | ![LLM Management API Keys list filtered to the default Active, Expiring soon, and Disabled statuses, with Expired and Revoked chips unselected; keys show Disabled, Expiring soon with days left, Active with no expiry, and Active with a Rotating note](https://mintcdn.com/barndoor/wVRWtdDvuAdONzeK/images/llm-gateway/11-api-keys-list.png?fit=max\&auto=format\&n=wVRWtdDvuAdONzeK\&q=85\&s=ca4ab4898cdda2c5baac44511e409821) A rejected key gets a `401` from the gateway. See [What callers see when something is denied](https://docs.barndoor.ai/how-tos/use-llm-controls.md#what-callers-see-when-something-is-denied). ## Create a Key With an Expiration 1. Go to **LLM Management → API Keys** and click **Create Key**, or to **Settings → My Models → API Keys** for a key of your own. 2. Enter a **Name**. On **LLM Management**, optionally **Assign to User** or **Assign to Group**. 3. Under **Expiration**, open the picker and choose when the key stops working: * a quick pick — **1 hour**, **1 day**, **7 days**, **30 days**, **90 days**, or **1 year**; * a date on the calendar, which expires at the end of that day (23:59) unless you type a time; or * **No expiry**, if your organization allows it. Use the **Local** / **UTC** switch to read and set the time in your own time zone or in UTC. The expiration is stored as a single moment, so it means the same thing wherever the key is used. 4. Click **OK**, then **Create**. ![Create API Key dialog on My Models with an expiration 30 days out and a note that the organization requires keys to expire within 90 days](https://mintcdn.com/barndoor/wVRWtdDvuAdONzeK/images/llm-gateway/01-create-api-key.png?fit=max\&auto=format\&n=wVRWtdDvuAdONzeK\&q=85\&s=e889e4d13747dee4289695935064340e) 5. Copy the key from the **API Key Created** dialog. It's shown only once — Barndoor keeps only a hash. When the expiration passes, the gateway rejects the key. Nothing else about it changes, so you can still see it, its bindings, and its usage history. > [!NOTE] > > If your organization has a [key policy](#limit-key-lifetimes-with-key-policies), the picker on **Settings → My Models** only offers expirations within your limit and says what the limit is. If your organization sets a fixed lifetime, there's no picker: the dialog shows when the key will expire instead. Keys created on **LLM Management** are exempt from key policies. ## Rotate a Key Rotating replaces a key's secret but keeps the key itself, so its ID, name, user or group binding, and usage history carry over. Rotate on a schedule, when a key is about to expire, or when a secret may have leaked. 1. Open the key's **⋮** menu and choose **Rotate**. On **Settings → My Models**, click the key's rotate icon. 2. Choose a **Grace period for the old key**: | Grace period | What happens to the old secret | | - | - | | **None** | Stops working immediately. Use this when a secret has leaked. | | **1 hour**, **24 hours**, **7 days** | Keeps working for that long alongside the new one, so you can update clients without an outage | 3. Set the **New expiration**. It starts at the key's current expiration, and leaving it unchanged keeps it. If the key has already expired, or its expiration is outside your key policy, you must pick a new one. ![Rotate API Key dialog with a 24-hour grace period for the old key and the new expiration left unchanged](https://mintcdn.com/barndoor/wVRWtdDvuAdONzeK/images/llm-gateway/12-rotate-api-key.png?fit=max\&auto=format\&n=wVRWtdDvuAdONzeK\&q=85\&s=5a5d1bd876762684f007a315234c778a) 4. Click **Rotate Key**, then copy the new secret. Like a new key, it's shown only once. While a grace period is running, the **Expires** column notes that the previous secret still works and until when. > [!TIP] > > To renew a key that's about to expire, rotate it with a later **New expiration** and a grace period long enough to roll the new secret out. For a user's own key under a fixed-lifetime policy, a rotation always renews the key to exactly that many days. ## Change a Key's Expiration Admins can extend, shorten, or remove a key's expiration without issuing a new secret, so the key's clients keep working unchanged. 1. On **LLM Management → API Keys**, open the key's **⋮** menu and choose **Change expiration**. 2. Pick the new expiration, or **No expiry**. 3. Click **Save**. * **Extending** takes effect at once. * **Shortening** also takes effect at once. The new expiration must still be in the future; to stop a key now, disable or revoke it. * **An expired key** becomes usable again, with the same secret, when you save an expiration in the future. Changing an expiration isn't limited by key policies, and it's only on **LLM Management**. On **Settings → My Models**, users renew their own keys by rotating them. ## Disable or Revoke a Key * **Disable** blocks the key temporarily. The secret stays issued, and **Enable** turns the key back on without handing out a new one. * **Revoke** blocks the key permanently. Applications using it lose access immediately, and it can't be rotated, extended, or re-enabled. To replace it, create a new key. ## Find and Act on Many Keys On **LLM Management → API Keys**: * **Search** by key name, user, group, or key ID. * **Filter by status** with the chips above the table. Each chip shows how many keys have that status. By default the list shows **Active**, **Expiring soon**, and **Disabled** keys; turn on **Expired** or **Revoked** to see those too, or click **Reset** to go back to the default. The filter is kept in the page address, so you can bookmark or share a filtered view. * **Sort** by any column, including **Status** and **Expires**. To act on several keys at once: 1. Click **Select keys**. 2. Tick the keys you want, or click **Select all** to take every key that matches the current search and filter, including keys on other pages. 3. Click **Disable**, **Enable**, or **Revoke**. Each button shows how many of the selected keys it applies to. A key that's already disabled isn't disabled again, for example. 4. Click **Cancel selection** when you're done. If some keys in a bulk action fail, the message names them; the others are still changed. On **Settings → My Models → API Keys**, expired keys are hidden until you tick **Show expired**. ## Limit Key Lifetimes With Key Policies **LLM Management → Key Policies** controls how long the API keys that users create for themselves may live. Keys that admins create on **LLM Management → API Keys** are exempt. > [!NOTE] > > Key Policies may not be enabled for your organization yet — contact Barndoor if you don't see **Key Policies** in **LLM Management**. ![Key Policies page with an organization default of at most 90 days, group overrides for contractors (exactly 30 days) and engineering (at most 180 days), and a user override with no limit](https://mintcdn.com/barndoor/wVRWtdDvuAdONzeK/images/llm-gateway/13-key-policies.png?fit=max\&auto=format\&n=wVRWtdDvuAdONzeK\&q=85\&s=7105eefa7913d52db4a21d8891414a6a) ### What a policy sets Each policy — the organization default, a group override, or a user override — combines three settings: | Setting | Effect | | - | - | | **Max lifetime** (days) | Keys must expire within this many days of being created or rotated. Leave it empty for no maximum. | | **Require an expiration** | Keys can't be created with **No expiry**. Implied when a max lifetime is set. | | **Fixed (users can't choose)** | Every key gets exactly the max lifetime, and users don't pick an expiration. Needs a max lifetime. | The policy list summarizes each one as **Exactly 30 days**, **At most 90 days**, **Expiry required**, or **No limit**. ### Set the organization default 1. Go to **LLM Management → Key Policies**. 2. Under **Organization default**, set the **Max lifetime** and the boxes you want. Leave the max empty and the boxes unticked for no limit. 3. Click **Save default**. ### Add group and user overrides An override replaces the default for the people it covers, so it can be longer or shorter than the default. 1. Under **Group overrides** or **User overrides**, search for and pick one or more groups or users. 2. Set the limit, then click **Add override** (or **Add user override**). Every group or user you picked gets its own override with the same settings, which you can then edit or remove one at a time. To exempt a group or a user, add an override with no max and no required expiration. ### Which policy applies For a given user, the gateway uses the first of these that exists: 1. **The user's own override.** It wins over everything else, so it can be looser or stricter than their groups and the default. 2. **Their group overrides.** A user in several overridden groups gets the strictest of those overrides. 3. **The organization default.** ### When a policy is checked A policy is checked when a user **creates** or **rotates** a key, on the portal and through the API alike. Changing a policy doesn't shorten keys that already exist: they keep their expiration until they're next rotated, and at that point the new expiration has to fit the policy. ## Expiration Alerts The gateway checks for expiring keys every 15 minutes and raises these [alerts](https://docs.barndoor.ai/how-tos/notifications.md): | Alert type | Severity | When it fires | | - | - | - | | **LLM API key expiring** | Warning | When a key has 7 days left, and again when it has 1 day left. A key created or extended into a window gets only the alert for the window it's in. | | **LLM API key expired** | Critical | Once, after the key's expiration passes | | **LLM API key revoked** | Info | When an admin or the key's owner revokes it | Each alert fires once per key and stage. Rotating or extending a key to a new expiration starts its alerts over. Each alert links to the key on **LLM Management → API Keys**. To receive these alerts, turn the alert types on for your inbox, email, or an organization-wide channel — see [Notifications](https://docs.barndoor.ai/how-tos/notifications.md). ## Manage Keys Through the API or Terraform Everything on this page is also available through the API — see **API Keys** and **Key Lifetime Policies** in the [LLM Gateway API reference](https://docs.barndoor.ai/api-reference/llm-gateway/introduction.md). To manage keys and key policies as code, use the [Barndoor Terraform provider](https://docs.barndoor.ai/terraform/llm-gateway.md). ## Troubleshooting > **A client suddenly gets 401 errors** > > Check the key's status on **LLM Management → API Keys**. Turn on the **Expired** and **Revoked** filter chips if you don't see it. An **Expired** key can be rotated or have its expiration changed; a **Disabled** key can be enabled; a **Revoked** key must be replaced with a new one. > **The expiration I want is greyed out** > > Your organization's key policy limits how long your keys may live. The picker says what the limit is. Ask an admin for an override, or for an admin-created key, which isn't subject to key policies. > **Rotating asks for a new expiration** > > The key has already expired, or its current expiration is outside your key policy. Keeping it would leave the new secret unusable or break the policy, so pick a new expiration. > **The old secret stopped working right after rotating** > > The rotation used a grace period of **None**. Rotate again with a grace period to give clients time, or update them to the new secret. ## Need Help? Contact [support@barndoor.ai](mailto:support@barndoor.ai) if you have questions about API keys or key policies. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.