Subscription accounts

Subscription accounts such as Codex, Claude, Antigravity, Grok, Muse Code, and Devin can use their channel's authorization flow or import existing credential JSON. Once connected, they share the same scheduler as API keys.

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 the channel's authorization flow or import existing credential JSON.
Credentials need maintenance — The gateway refreshes credentials or verifies account status according to the channel. If authorization fails, refresh manually or reconnect.
Quota support varies by channel — When the upstream supports quota queries, the console shows remaining quota and reset times. Missing information does not mean zero quota.

Connect an account §

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

The connection account panel of Codex subscription Group, showing OAuth authorization link and callback address input box — FIG. 1 — Connect accountAuthorization Entry

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

Local callback (Codex, Claude, Antigravity, Devin) — After browser authorization, the upstream redirects to a fixed local port where the gateway receives the authorization code.
Device code (Grok, Muse Code) — Enter the code shown by GPT-Load on the upstream website to authorize the account; no callback port is required.
Import credential JSON (all six subscription channels) — Upload or paste credential JSON for the channel; no local callback is required on this machine.

Import supports CPA-compatible credentials (including Meta/Muse and Devin), official Codex, official Claude Code, and sub2api OAuth JSON, including multiple files or account arrays. PATs are unsupported; each channel's required authorization fields must be present.

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.

Muse Code§

Muse Code uses device authorization without a callback port. Imported CPA Meta/Muse credentials must include a DCA token. Authorization or import exchanges it for a request key at the official endpoint and confirms an active subscription; an API-key-only file cannot replace this flow.

Model discovery reads the model list actually returned for the account. Active quota queries are currently unavailable; missing quota information does not mean the quota is exhausted. Contributor Mode is always disabled.

Devin§

Devin uses browser authorization with the fixed callback URL http://127.0.0.1:17326/callback. You can also import CPA Devin credentials containing session_token or api_key. Both authorization and import verify the upstream account identity.

When pasting a Devin callback URL manually, keep 127.0.0.1, port 17326, and /callback. Do not change the host to localhost; a mismatched host, port, or path is rejected.

Devin uses long-lived session tokens. Refresh credentials only verifies identity and account status; it does not rotate the token or infer an expiry time. Quota sync can show daily and weekly remaining percentages and reset times. Fields omitted by the upstream remain unknown rather than being treated as zero.

Devin model discovery verifies the account, then returns the model catalog bundled with the release. A listed model is not necessarily available to the current account. All four conversation protocols use conversion; see the support matrix for the exact boundaries.

Callback port §

The four 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
Devin	17326	Callback URL: http://127.0.0.1:17326/callback
Grok · Muse Code	Not needed	Device code authorization, does not occupy local port

Docker Compose publishes the three callback ports for Codex, Claude, and Antigravity by default and, like the main service, bind only to 127.0.0.1:

Port publishing in docker-compose.yml

ports:
  - "${BIND_ADDRESS:-${HOST:-127.0.0.1}}:${PORT:-3001}:${PORT:-3001}"
  - "${OAUTH_CALLBACK_BIND_ADDRESS:-${HOST:-127.0.0.1}}:1455:1455"   # Codex
  - "${OAUTH_CALLBACK_BIND_ADDRESS:-${HOST:-127.0.0.1}}:54545:54545" # Claude
  - "${OAUTH_CALLBACK_BIND_ADDRESS:-${HOST:-127.0.0.1}}:51121:51121" # Antigravity

The default Compose file does not publish Devin's port 17326. You can paste the complete callback URL manually or import credentials. To receive local callbacks automatically, add "127.0.0.1:17326:17326" under ports; use SSH forwarding as well for a remote deployment.

Callback ports only limit local authorization

Only one instance can bind a given fixed callback port at a time. Other instances can import existing credential JSON; Grok and Muse Code can also use device authorization.

How to authorize remote deployment §

This is the most common stumbling block. When the service runs on a remote server, localhost / 127.0.0.1 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:

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 localhost reaches the server:

SSH Port Forwarding (using Codex as an example)

ssh -L 1455:127.0.0.1:1455 user@your-server

 # Use 54545 for Claude, 51121 for Antigravity, and 17326 for Devin 
 # Forwarding: complete authorization during connection maintenance

If you already have credential JSON for the channel, upload or paste it to import without a callback port.

Do not open to the public network for authorization

Do not expose callback ports to the public internet. Paste the callback URL manually, use SSH forwarding, or import existing credential JSON; there is no need to set 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	The gateway is refreshing the credentials	Just wait, usually completes in a few seconds
Reauthorization required	The upstream rejected the refresh, or the existing authorization is no longer valid	Try refreshing the credentials; reconnect or import the account if it still fails
Unknown result	The refresh request did not get a clear result, possibly a network issue	Try refreshing the credentials; reconnect or import the account if it still fails

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.

Subscription account credential list, showing account status, quota window, and reset time — FIG. 2 — Account listStatus · Quota · Reset time

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.

Quota and cooldown recovery

Quota values do not determine rotation order; upstream rate-limit responses still trigger cooldowns and switching. Quota is updated through active synchronization and upstream responses and may be delayed.

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.

Codex credit balance

Open a Codex group and click Sync quota in Modern or Sync in Classic. Account cards show Credits when the upstream reports a positive balance or unlimited credits. An absent label does not establish a zero balance.

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

Codex and Claude reset credits

Codex and Claude accounts may offer reset credits; account cards show available credits and expiration. Credits are consumed only after manual confirmation, never automatically. Refresh quota information afterward to verify the result. If the outcome is unknown, check the original operation rather than starting another reset.

Codex subscription information §

In a Codex group, click Sync quota (Sync in Classic) to fetch quota, reset credits, and subscription information concurrently. Modern account cards and Classic account details can show the subscription period end and renewal status. Subscription expiry and OAuth credential expiry are separate.

If the upstream omits the renewal flag, the status is Renewal unknown. When the subscription lookup fails, previous values are retained with a warning; without previous values, the information is shown as unavailable. An upstream 404 clears the old subscription information.

The latest observation time is not a separate confirmation time for subscription information. A successful quota sync does not mean that subscription information was confirmed by the same lookup. Also check for subscription errors or warnings about previous values.

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.