Subscription accounts

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 OAuth authorization or import existing OAuth JSON
• 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.

Click to view

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.

There are three connection methods, depending on the channel and whether you already have authorized credentials:

• 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.
• Import OAuth JSON (all four subscription channels) — upload or paste existing OAuth JSON; no local callback is needed on this machine

Callback port §

The three local-callback channels use ports fixed by the upstream clients; they cannot be customized:

Docker Compose publishes all three ports by default and, like the main service, bind only to 127.0.0.1:

ports:
  - "$${BIND_ADDRESS:-${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

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 three ways to solve this; choose one:

1. 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.
2. SSH Port Forwarding — Forward the server's callback port to your computer so localhost reaches 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 

If you already have OAuth JSON, upload or paste it directly; no callback port is needed.

Four authorization states §

Each subscription account has an authorization status; check it first when troubleshooting:

Click to view

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:

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.