Subscription accounts
Subscription-based accounts such as Codex, Claude, Antigravity, and Grok use OAuth instead of API keys. Once connected, they share the same scheduler as API-key credentials.
How subscription accounts differ from API keys §
To the gateway, subscription accounts and API keys are simply credentials in a pool: they share the same rotation, retry, cooldown, and health-isolation mechanisms. No separate operational workflow is required for subscription accounts.
Differences only in three places:
- Access method — Complete an OAuth authorization flow instead of pasting a key.
- Credentials will expire — The gateway refreshes credentials automatically. A failed refresh moves the account into the reauthorization-required state.
- Has a quota window — Subscription quotas reset periodically; the management UI shows remaining quota and reset time.
Connect an account §
Subscription accounts also belong to a Group. Open Group → Import channel credentials → Create new Group, choose Subscription Account as the connection method, select Codex, Claude, Antigravity, or Grok, and complete authorization.
The authorization panel stays expanded. Remote deployments often require copying the authorization link and callback URL manually, so this is a primary workflow rather than a fallback.
The authorization flow depends on the channel and has two forms:
- Local callback (Codex, Claude, Antigravity) — After browser authorization, the upstream redirects to a fixed local port where the gateway receives the authorization code.
- Device code (Grok) — Enter the code shown by GPT-Load on the upstream website to authorize the account; no callback port is required.
Callback port §
The three local-callback channels use ports fixed by the upstream clients; they cannot be customized:
| Channel | Callback port | Explanation |
|---|---|---|
| Codex | 1455 | Callback URL http://localhost:1455/auth/callback |
| Claude | 54545 | Fixed by upstream client |
| Antigravity | 51121 | Fixed by upstream client |
| Grok | Not needed | Device code authorization, does not occupy local port |
Docker Compose publishes all three ports by default and, like the main service, bind only to 127.0.0.1:
ports: - "$${HOST:-127.0.0.1}:$${PORT:-3001}:$${PORT:-3001}" - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:1455:1455" # Codex - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:54545:54545" # Claude - "$${OAUTH_CALLBACK_BIND_ADDRESS:-...}:51121:51121" # Antigravity
Because the upstream fixes these ports and they cannot be changed, only one default Compose instance can run on a host at a time. If you run multiple instances, only one can use local-callback authorization; use a device-code channel for the others or temporarily stop the instance holding the port while authorizing.
How to authorize remote deployment §
This is the most common stumbling block. When the service runs on a remote server, localhost in your browser points to your own computer, not the server, so the post-authorization redirect fails.
There are two solutions, choose either one:
- Manually paste callback address — If the redirect fails, copy the complete callback URL from the browser address bar and paste it into the management UI's callback field. The gateway extracts the authorization code and completes the flow. This is the most broadly applicable method and requires no network changes.
- SSH Port Forwarding — Forward the server's callback port to your computer so
localhostreaches the server:
ssh -L 1455:127.0.0.1:1455 user@your-server # Claude uses 54545, Antigravity uses 51121 # Forwarding: complete authorization during connection maintenance
Callback ports must not be exposed to the public internet. Either method above completes authorization without changing OAUTH_CALLBACK_BIND_ADDRESS to 0.0.0.0.
Four authorization states §
Each subscription account has an authorization status; check it first when troubleshooting:
| Status | Meaning | What to do |
|---|---|---|
| Ready | Credential is valid, participating in scheduling normally | No Processing Required |
| Refreshing | Credential is about to expire, gateway is automatically renewing | Just wait, usually completes in a few seconds |
| Reauthorization required | Auto refresh failed, mostly because the upstream revoked authorization or the password was changed | Go through the authorization process again |
| Unknown result | The refresh request did not get a clear result, possibly a network issue | Observe first, reauthorize if the issue persists |
Quota windows, reset times, and authorization status appear on the same screen.
How to interpret quota information §
The management UI shows remaining quota and reset times for subscription accounts, but keep one distinction in mind:
Quota information does not participate in scheduling decisions. Quota data is observed passively from upstream responses, may be delayed, and may not cover every billing dimension. The real trigger for account switching is the rate-limit response returned by the upstream: when an account is rate-limited, the gateway immediately puts it into cooldown and switches accounts regardless of the displayed quota.
Use the quota column to let you decide whether to add another account, not to predict which account the gateway will choose next. To confirm candidate Groups and available credentials, use Route Check in Monitoring and troubleshooting.
Usage prerequisites §
- Only connect to accounts you are authorized to use and follow each provider's subscription terms. Sharing or reselling subscription quota is usually prohibited.
- Subscription channels depend on upstream OAuth and compatible protocols. You may need to update when upstream changes; these changes are outside the gateway's control.
- Credentials are encrypted locally, but the key that can decrypt the credentials and the database must be backed up together. See Security and production.