Keys
A Budget AI key is what an application or agent presents to the gateway. Keys are issued per project in Budget AI → Keys. A key can call only the model groups it is granted, only until it expires, and only within its limits.
Key format and use
- Keys look like
sk-ants-followed by 40 letters and digits. - Send the key as
Authorization: Bearer <key>or as anapi-key: <key>header. OpenAI SDKs do the first when you pass the key asapi_key/apiKey. - The full key is shown once, when it is issued or collected. ANTS Platform stores only a salted hash and the last four characters, which the Keys table shows. A lost key cannot be recovered; rotate it instead.
- Keys work only on the instance that issued them.
Issue a key
You need gatewayAi.keys:write. Placing the key in an org unit also needs gatewayAi.budgets:admin.
Open the issue form
Go to Budget AI → Keys and select Issue key.
Choose how the key is delivered
- Show me the key: the key is created now and shown to you to pass on.
- Send a collection link: enter the Developer's email. No key exists until that person collects it. See Collection links.
Fill in the key
| Field | Notes |
|---|---|
| Alias | A name for the key, up to 64 characters, unique in the project. Shown in traces as gateway.key_alias. |
| Model groups | At least one. The key may call only these groups, and GET /v1/models lists exactly these. |
| Expires in | Required. A number of hours or days. See Expiry. |
| Budget in USD (optional) | Creates a key budget. See Budgets on keys. |
Under Advanced settings:
| Field | Notes |
|---|---|
| Recording | Project default or Usage only - store no prompt or response text. See Recording mode. |
| Requests per minute (optional) | Key RPM limit, 1 to 10,000,000. Empty means no key limit. |
| Tokens per minute (optional) | Key TPM limit, 1 to 10,000,000. Empty means no key limit. |
| Org unit | The unit whose budgets also apply to this key, or None: an independent key. See Budgets & Limits. |
| Tags (comma separated, optional) | Up to 20 tags of up to 64 characters. Tags select tag budgets and filter the Keys table. |
| Allowed source networks (optional) | See Allowed source networks. |
| Guardrail checks | Project default, On or Off. See Guardrails. |
Confirm
Select Issue key (or Create link) and complete step-up verification.
With Show me the key, the key is displayed with ready-made snippets for the OpenAI Python SDK, the OpenAI Node SDK and curl, using your gateway address. Copy it into your secret manager before closing the dialog.
Collection links
A collection link lets a developer collect their own key, so the key is never handled by anyone else.
- The link names one email address. Only a signed-in account with that address can collect the key, and only if the address is verified or the person signs in through your identity provider.
- If email is configured on the instance, the link is emailed. Otherwise you copy it and send it yourself. The link is safe to send over chat: it does nothing without a sign-in as that person.
- The link works for 72 hours and for one collection. Anyone else who opens it is told the link is not for them.
- The key is created when the link is collected, and its expiry counts from that moment. The key's settings are checked again at collection against the project's current policy, for example the maximum expiry.
- The developer sees Here is your key once, with the key's expiry, budget, rate limits and the model groups it can call.
- If you can invite members, Also give them access to this project adds the person to the organization and project as End User, so they can sign in. Without it they can call the gateway but have nothing to sign in to.
Creating and collecting a link are both written to the audit log, with who issued the link and who collected the key.
Expiry
Every key has an expiry date.
| Setting | Default | Where |
|---|---|---|
| Default key expiry | 90 days | Project Settings → Budget AI → Key policy and project limits |
| Maximum key expiry | 365 days | Same place, up to 3650 days |
Expiry can be set in hours or in days, so a key can last only as long as the task it is for. A key's expiry must be in the future and within the project's maximum, whichever unit is used.
The gateway checks expiry on every request. At expiry it refuses the key with 401 key_expired, and the key's expiry is written to the audit log. Expired keys stay in the table so the refusal names the reason.
Keys with less than 24 hours left show a countdown to their expiry in the Keys table. The Keys page also counts keys expiring within the next seven days. No notification is sent to the key's owner before expiry, so rotate keys ahead of time.
Key status
| Status | Meaning |
|---|---|
| active | The key works |
| retiring | The key has been rotated and works until its grace window ends |
| blocked | Every request is refused with 401 key_blocked |
| expired | Past its expiry or the end of its grace window; refused with 401 key_expired |
Key actions
Each row's menu offers the actions you have permission for:
| Action | What it does | Permission | Step-up |
|---|---|---|---|
| Limits | Shows every budget that applies to the key, with period, amount, spend, remaining and which budget is binding | gatewayAi.budgets:read and gatewayAi.keys:read | No |
| Network access | Edits the allowed source networks | gatewayAi.keys:write | Yes |
| Rotate | Issues a replacement key, see Rotation | gatewayAi.keys:write | Yes |
| Block | Refuses every request with the key within a few seconds. The key, its limits and its spend are kept. | gatewayAi.keys:admin or tenantSecurity.gatewayKeys:admin | No |
| Unblock | Puts a blocked key back into service | gatewayAi.keys:admin or tenantSecurity.gatewayKeys:admin | Yes |
| Delete | Removes the key. Any application still using it stops working immediately. | gatewayAi.keys:admin | No |
Blocking is the reversible way to stop a key. Prefer it to deleting when you may need the key's history or want to undo the action. Security & Compliance members can block and unblock keys through tenant security without being able to issue keys or change credentials.
Moving a key to another org unit is done from Budgets & Limits → Hierarchy and needs gatewayAi.budgets:admin.
Rotation
Rotation issues a new key with the same settings and gives applications time to switch.
Start the rotation
Select Rotate on an active key.
Choose when the old key stops
- Keep the old key working for 24 hours: both keys work while you redeploy. The old key stops on its own when the window closes.
- Revoke the old key immediately: anything still using the old key fails now. Choose this if the key may have leaked.
Choose the new key's lifetime
- Keep the current expiry: rotating does not extend a date the project already set.
- Start a fresh lifetime: pick a number of days up to the project maximum.
Choose whether to copy budgets and tags
Copy budgets and tags to the new key keeps the key budget's amount, period, enforcement and thresholds, and carries this period's spend over, so rotating cannot reset a cap. A key with a hard budget always carries it over.
Confirm
Select Rotate key and complete step-up verification. The new key is shown once.
Model groups, rate limits, recording mode, org unit, expiry and the network allow-list always carry over. The new key's alias is the old alias with (rotated <date>) added. The old key shows as retiring until its window ends.
Blocked and expired keys cannot be rotated, and a key cannot be rotated again while a rotation is in progress.
While both keys are live during a grace window, each spends against its own budget, so combined spend can exceed the cap until the window closes. Revoke immediately to avoid that.
Short-lived keys for agents
An authorised system, such as an orchestrator that starts agents, can mint a short-lived key for one agent and one task through the key minting API. The request names the agent, the lifetime in hours, the model groups and, optionally, a budget, rate limits and allowed source networks. For example: agent invoice-reader, 2 hours, the prod-chat model group, a 5 USD budget.
- The key is bound to the named agent. See Keys bound to an agent.
- Its lifetime is capped by the project's maximum key expiry, the same as keys issued in the Keys screen.
- The key is returned once, in the API response. It then appears in the Keys table like any other key, with its expiry countdown.
- Minting is written to the audit log with the project API key that made the request.
When the lifetime ends, the gateway refuses the key with 401 key_expired. Nothing has to revoke it.
Keys bound to an agent
A key can be bound to one agent. Keys minted through the key minting API are always bound to the agent named in the request.
Suspend agent in the AI Agent Center blocks every key bound to the agent in one transaction, so an agent with several keys (production and staging, or old and new after a rotation) is stopped by one action. The keys show as blocked and are refused with 401 key_blocked. Resume agent puts them back into service and needs step-up verification. Rotating a bound key keeps the binding.
Allowed source networks
A key can be confined to source networks. Enter IPv4 or IPv6 addresses or CIDR ranges, up to 50, when issuing the key or later with Network access. Requests from any other address are refused with 403 ip_not_allowed before they reach a provider. The refused attempt is recorded with the caller's address (gateway.source_address) so you can see where it came from.
An empty list allows any source. The gateway determines the caller's address from the proxies in front of it; on a self-hosted deployment this must be configured correctly. See Self-Hosting & Configuration.
Recording mode
| Mode | What is stored |
|---|---|
| Full (project default) | Prompts and responses are stored on the trace, like any SDK trace |
| Usage only | No prompt or response text is stored. Token counts, cost, model, latency, routing detail, limits and caller attribution are kept. |
Choose Usage only for keys that carry sensitive content. A usage-only key also never writes to the response cache. Recording mode is chosen when the key is issued and carried over on rotation. Usage-only traces carry gateway.logging_mode = usage_only.
Budgets on keys
Budget in USD on the issue form creates a key budget that resets monthly and is alert only: it records threshold crossings at 50 %, 80 % and 100 % but does not stop requests. To make it stop requests, or to change its period or thresholds, edit it in Budgets & Limits and set When reached to Stop requests. See Budgets & Limits.
The Spend vs budget column on the Keys table shows the key's spend against that amount.
What happens to refused requests
Refusals for blocked, expired or network-confined keys are recorded as traces at most once per minute per key and reason, so a withdrawn key cannot be used to fill your project with traces. Further attempts are counted in gateway metrics only. Requests with an unknown key are never traced.
Audit trail
Issuing, minting through the API, rotating, blocking, unblocking, deleting, changing networks, moving a key between org units, expiry, and suspending or resuming the key's agent are each written to the audit log with before and after values. Key material never appears in the audit log, traces or logs.