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 and cost limits.
This separation makes it natural to issue separate keys to different applications: each key has independent limits and revocation.
An enabled, unexpired AccessKey can sign in to this instance, but it can only view its scoped home page, models, usage, and redacted request logs. It cannot modify Groups, AccessKeys, or runtime settings, and it cannot view upstream credentials.
Create a key §
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.
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.
Cost ceiling §
A more direct safeguard than RPM is to cap spending. Two rule types are available:
- Total Quota — Stops when cumulative spending reaches the limit and never resets. Suitable for one-time keys issued to external collaborators.
- Periodic quota — Resets each period. Configure a period from one minute to one year; daily and monthly periods are common.
Cost limits use the gateway's estimated cost, calculated from upstream token usage and model prices; they do not equal the provider's invoice. Models without pricing data do not count toward the limit. Use cost limits to prevent accidental runaway usage, not for exact financial control. See Monitoring and troubleshooting for the accounting rules.
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.
The management UI's Rotate key generates a new secret on the existing record while preserving its name, permissions, and quota settings. After rotation succeeds, the old secret becomes invalid immediately; requests already in progress are unaffected. There is no dual-key grace period, making this suitable for cutting off a confirmed leak immediately.
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.