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 an OAuth authorization flow or import existing OAuth JSON.
• Credentials will expire — The gateway refreshes credentials automatically. If authorization fails, try a manual credential refresh or reconnect the account.
• Has a quota window — Subscription quotas reset periodically; the management UI shows remaining quota and reset time.

Connect an account §

Subscription accounts belong to Groups. Open Groups → New Group, select Codex, Claude, Antigravity, or Grok, then connect an account or import credentials.

View full size

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; a local callback on this machine is not required.

Import supports CPA-compatible, official Codex, official Claude Code, and sub2api OAuth JSON, including multiple files or account arrays. PATs and files missing required refresh credentials are unsupported.

Subscription Groups may use a custom HTTPS upstream root URL or path prefix. The relay must handle that channel’s calls, model discovery, and quota queries; business requests do not implicitly fall back to official URLs. OAuth authorization and token refresh still use official endpoints.

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:

Use Refresh credentials in the account card menu to restore authorization. Refresh quota updates quota information and also clears quota cooldowns when recovery conditions are met. Manually disabled accounts must be enabled before refreshing credentials.

View full size

Quota windows, reset times, and authorization status appear on the same screen.

How to interpret quota information §

After the first import, sync quota to fetch the current quota and reset time. If quota data does not update or looks incorrect after an upgrade, refresh it manually once.

When a fresh quota observation shows a drop of at least 5 percentage points in the used quota of a uniquely matched window, the account and its models are released from quota cooldowns. This applies to active synchronization and passive updates. Other cooldowns, including custom rules, authorization, disabled or blacklisted states, and failure counts are unchanged.

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.

Credits are displayed separately from periodic quotas and reset credits. They are not added together and do not affect scheduling.

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.