Core concepts
There are only two things to worry about in the management UI: Groups and AccessKeys. Understand what each manages, and the rest of the documentation becomes easy to read.
Only two layers §
Many gateways make you manage providers, keys, and routing rules separately. GPT-Load reduces them to two layers:
- Group — Everything about the upstream connection: provider, credentials, exposed models, and runtime policy.
- AccessKey — The key given to an application: allowed Groups, protocols, and limits.
In short, Groups connect to upstream services; AccessKeys authorize applications. The gateway handles scheduling, retries, cooldown, and usage accounting between the two.
Group: the half facing upstream §
A Group ties five things together:
- Channel — Choose one of the twenty built-in upstreams; it determines the request's final destination.
- Access method — Choose between API keys and subscription-account authorization.
- Credential Pool — One or more keys or accounts that the gateway rotates between.
- Available models — The models this Group exposes.
- Runtime policy — Weight, timeouts, retries, cooldown threshold, and outbound proxy.
Everything in a Group is organized into three tabs: Credential Pool, Models & Aliases, and Runtime Policy.
Channels are not created independently §
The management UI has no standalone Channel menu. Choose a channel while creating a Group on the Import Channel Credentials page. Common channels appear as buttons; the rest are under Other Channels. Once selected, that Group stays tied to the chosen upstream. Create two Groups for two providers.
Changing providers usually changes the credentials, available models, and rate-limit behavior together. Keeping one Group tied to one upstream service avoids updating those settings in three separate places.
Two access methods with the same scheduling. §
When creating a Group, choose the connection method that determines the credential type:
- API Key — Paste one or more keys; this is the most common method.
- Subscription accounts — Use OAuth for subscription-based accounts such as Codex, Claude, Antigravity, and Grok.
Both use the same scheduling, retry, cooldown, and health-isolation logic. You do not need separate operations for subscription accounts; to the gateway, they are simply credentials in a pool. See Subscription accounts for authorization details.
AccessKey: the half facing the application §
An AccessKey is the string you give to an application. It does not bind directly to an upstream; it declares only three things:
- Which Groups can be used — Select one or more; the gateway chooses one based on the requested model and current health.
- Which protocols can be used — OpenAI Chat Completions, Responses, Anthropic Messages, and Gemini
- Quota — requests per minute, plus a cost cap (either a total quota that never resets, or one that resets each period)
This separation makes it natural to issue different keys for testing, production, or individual users. Each has independent limits and revocation, without affecting the others. See AccessKey for details.
Group does not appear in the URL §
In 1.x, the Group name was part of the request URL. 2.0 does not: applications use one fixed base URL, while the AccessKey scope and requested model determine the Group.
This makes an upstream change completely transparent to applications: you can edit Group settings, add or remove credentials, or switch providers without changing the application's endpoint or key.
How many Groups to create §
There is no single answer, but two practical rules help:
- Divide by upstream — This is mandatory: one Group can connect to only one channel.
- Divide according to policy — Split one provider into separate Groups when key sets need different priorities, fallback roles, timeouts, or retry policies.
Conversely, multiple keys from the same provider do not need to be split into Groups. Put them in one credential pool so the gateway can rotate between them and route around failures.