AccessKey
An AccessKey is the secret you give to an application. It is not bound to any upstream; it defines which resources the application can access, where it may connect from, and how much it may use.
What it manages §
Groups connect to upstream services; AccessKeys authorize applications. An application receives one key and does not need to know about the Groups or upstream credentials behind it.
An AccessKey defines four kinds of boundaries:
- Resource scope — which Groups and client-visible models it may use
- Protocol scope — which client protocols it may use
- Access conditions — allowed source IPs/CIDRs and expiration
- Usage boundaries — Requests per minute, concurrency limits, and cost caps
This separation makes it natural to issue separate keys to different applications: each key has independent limits and revocation.
An enabled, unexpired access key can sign in to this instance to view its own home overview, models, usage, and request logs, including its original request bodies when recording is enabled. It cannot modify groups, access keys, or runtime settings, or view upstream credentials.
Create a key §
Customize the key or generate it randomly. Leaving it blank creates a generated key on creation and preserves the existing key on editing. Random generation updates only the draft until saved.
Open AccessKey → Create new, select the allowed Groups and protocols, set any limits, and save to generate the key.
After creation, the key is masked by default. Reveal its full value explicitly only when needed.
The key is an application's only gateway credential. Do not commit it to a repository or expose it in logs or public issues, and do not share one key across applications because you cannot revoke them independently.
Request body recording is off by default and enabled separately for each access key; there is no global switch. As an administrator, enable Record request bodies when creating or editing a key, accept the privacy notice, and save. Existing keys also remain off by default.
Recorded content may include conversations, tool arguments, image data, personal information, or keys. Enable it only when authorized and needed for troubleshooting, then turn it off. Notify API-only users separately. Key holders see a persistent notice when signed in to the console and can view recorded content. Turning recording off does not delete saved history.
Authorization Scope §
An AccessKey can authorize multiple Groups and further restrict access by client-visible model name. When a request arrives, the gateway determines which to use based on the model name in the request and the Group's health.
This enables two useful patterns:
- Multiple sources for the same model — If two Groups expose the same model, the gateway automatically uses the other when one is unavailable, without application changes.
- Narrow as needed — grant only the Groups and models the application needs, preventing accidental use of other resources
An empty Group, protocol, or model list means that dimension is unrestricted. When multiple values are present, any one may match; all different dimensions must be satisfied together.
Protocol Selection §
Select the client protocols this AccessKey may use. Requests using an unselected protocol are rejected.
- OpenAI Chat Completions — The broadest compatibility; most compatible clients use this protocol.
- OpenAI Responses — A newer API that supports stateful requests.
- Anthropic Messages — The native endpoint for Claude Code and similar clients.
- Gemini — The native endpoint for Gemini clients.
When unsure, select every protocol the application actually uses. See Protocols and conversion boundaries for capability differences.
Source and expiration §
You can add two authentication conditions to an AccessKey:
- Source IP/CIDR — leave empty to allow any source; when set, only matching IPv4, IPv6, or CIDR sources are allowed
- Expiration — choose no expiration or a future time; after expiration, new requests and read-only management UI sign-ins are rejected
Source restrictions match the address directly connected to GPT-Load; they do not read X-Forwarded-For or X-Real-IP. Behind a reverse proxy, allow the proxy server address rather than the end-user address in most deployments.
Rate limiting §
Requests per minute (RPM) limits how frequently this AccessKey may be used. Excess requests are rejected; leave it empty or set it to 0 for no limit.
Its purpose is to prevent one application from running out of control. For example, a faulty loop should not consume all upstream quota.
Concurrency limit caps active requests for this key across Groups. Leave it blank to inherit the system default; 0 removes the key-specific limit. Global and Group limits still apply.
View concurrency limits and rejection behavior →
Cost ceiling §
It limits later requests using cost estimated by the gateway, with two rule types:
- Total quota — rejects later requests after cumulative estimated cost reaches the threshold and never resets. Suitable for a one-time key issued to an external collaborator
- Periodic quota — Resets each period. Configure a period from one minute to one year; daily and monthly periods are common.
Cost limits accumulate the final cost after applying the Group and AccessKey price multipliers; both default to 1.
The gateway charges estimated cost only after a request completes. One large request or concurrent requests already admitted may exceed the threshold; requests without pricing or usage are not counted. This protects against accidents but is not a provider bill or strict financial cap.
Review cost-limit boundaries →
Review the cost estimation method →
Disabling and rotation §
A key has two states: Enable / Disable. Disabling it takes effect immediately while retaining the configuration for later re-enabling, which is useful during troubleshooting.
Enter a new value or generate one in the key editor, then save to replace the key. Its ID, permissions, limits, and consumed amount are retained. Once saved, the old key is invalid immediately; in-flight requests are unaffected. There is no two-key grace period.
If you require zero-downtime rotation, create a second AccessKey, update and verify the application, then disable or delete the old AccessKey.
Recommendations §
- Use one key per application. Sharing a key obscures attribution and prevents independent revocation.
- Issue a separate key to test environments with a lower cost limit; accidental loops during debugging can consume quota quickly.
- Grant only the required scope. A read-only demo does not need access to Groups containing expensive models.
- Set source restrictions and an expiration for external or temporary applications. This reduces the usable scope after a leak
- Cap externally issued keys with a total cost limit; a total limit is more predictable than a periodic one.