Connect official subscription accounts

Connect ChatGPT / Codex, Claude, Gemini CLI / Code Assist, and Antigravity through OAuth, configure models, and grant gateway access.

Administrator task guideUpdated Oct 28, 2026

Prepare an account and administrator access

Use an eligible upstream account and a console account allowed to manage the channel. Super administrators manage public channels; organization administrators manage their organization’s private channels. Subscription channels follow organization bindings, model permissions, gateway keys, quotas, and usage recording.

The account holder can sign in through an authorization link copied by the administrator without accessing BOS Admin. Application developers continue to use a BOS API gateway key; administrators maintain the upstream subscription authorization in the channel.

Create a channel and complete official sign-in

Authorization links last ten minutes, are bound to the initiating administrator, organization, role, and platform, and can be exchanged once. Start a new sign-in after expiry or token-exchange failure and paste the new session’s result.

  • In Channels and models, add a channel and enter a name. Select OpenAI, Anthropic, Gemini, or Antigravity and Official subscription (OAuth). New channels default to subscription sign-in; select the appropriate credential mode for an API key or upstream proxy. Subscription endpoints and protocols are filled automatically and pinned to the official service.
  • Choose Start official account sign-in and complete sign-in in the new tab, or copy the authorization link for the account holder. If the popup is blocked, use Open official sign-in page or copy the link. Keep the original form open.
  • Paste the complete final callback URL or displayed authorization code into the same form. Claude also accepts code#state. Do not mix results from another tab or an earlier authorization session.
  • Choose Save Channel at the bottom of the form. Models may be empty: the account is saved before model discovery is attempted. Save and discover models in the model section performs both steps. Signing in on the official page alone does not save the channel.

Continue when the localhost callback cannot open

OpenAI may redirect to localhost:1455/auth/callback; Antigravity uses localhost:8085/callback. ERR_CONNECTION_REFUSED usually means there is no local callback listener and alone does not establish an OAuth denial. Copy the entire address, including code and state, paste it into the original BOS form, and save.

This flow does not require publishing a callback port on the deployment server and does not return to BOS automatically. The account is connected only after BOS successfully exchanges the code and saves the channel.

Discover models and grant request access

  • OpenAI, Claude, and Antigravity use the authorized account’s official model catalogs. A discovery failure preserves the saved account; retry from the model drawer or edit the channel to add model names manually. A channel without configured models cannot serve model requests.
  • Gemini CLI / Code Assist has no equivalent model catalog here. Discovery checks account connectivity and retains manually configured models without inventing models or token limits. Add only models the account can actually use.
  • Explicitly bind and enable a public channel for the organization; private channels follow their organization’s permissions. Issue a gateway key authorized for the models. Test a small request using the matching protocol, then streaming and tool calls, and verify usage and the Request ID.

Choose the protocol for each account

AccountPrimary interface and supportLimits
ChatGPT / CodexResponses JSON / SSE and existing Codex WebSocket and compaction routes.Chat / Messages compatibility is limited to plain non-streaming conversations. Use Responses for Codex tools and streaming. Subscription OAuth does not grant OpenAI embeddings or image API access.
ClaudeMessages JSON / SSE, count_tokens, and existing Chat conversion.Use an authorized model with the Anthropic protocol; existing cross-protocol limits still apply.
Gemini CLI / Code AssistGemini generateContent JSON, streamGenerateContent SSE, and existing Chat / Messages conversion.Token counting depends on access to Google’s generative-language endpoint. Code Assist embeddings are unsupported. A consumer Gemini subscription does not guarantee Code Assist or all model access.
AntigravityGemini generateContent JSON, streamGenerateContent SSE, and existing Chat / Messages conversion.Uses its own OAuth client and project identity. Token counting is unavailable and returns a capability error.

Gemini project discovery and troubleshooting

Gemini first resolves a managed project through loadCodeAssist. Eligible new users can be onboarded automatically while BOS waits for asynchronous operations. If no project is returned, BOS queries existing ACTIVE Google Cloud projects with the same account token, preferring a unique Code Assist / companion project, then a unique default project, then the sole remaining project. It does not create Cloud projects, enable APIs, or change billing.

If there is no accessible project or multiple equally suitable candidates, enter the account’s Google Cloud Project ID in the authorization form and authorize again. Google permission and operation errors are reported directly; inspect the error and account eligibility rather than treating a missing project as success. Antigravity also accepts a project ID in its authorization form.

Deployment and optional OAuth clients

The updated backend includes separate default OAuth clients for Gemini CLI and Antigravity. When both variables for a platform are empty or unset, the built-in default requires no extra configuration. Set both only to use another compatible client. An incomplete pair causes authorization and refresh configuration errors; the platforms do not share clients.

Optional overrides: leave empty for built-in clients
BOS_GEMINI_OAUTH_CLIENT_ID=
BOS_GEMINI_OAUTH_CLIENT_SECRET=
BOS_ANTIGRAVITY_OAUTH_CLIENT_ID=
BOS_ANTIGRAVITY_OAUTH_CLIENT_SECRET=

For Compose, edit the server’s existing private deploy/stack.env, preserving database passwords and encryption keys. These values identify the OAuth application and differ from upstream API keys, user access tokens, and callback authorization codes.

Apply runtime configuration changes
./deploy/stack.sh start

Run in the application deployment directory after updating the backend and Compose definition. This uses existing images and recreates containers whose environment changed. docker restart or docker compose restart does not inject new environment values. Rebuild and deploy source changes first.

  • A custom Gemini client must register https://codeassist.google.com/authcode; Antigravity must register http://localhost:8085/callback.
  • The deployed stack does not read backend/.env.example. For a directly launched backend, set variables in the process environment and restart it.
  • Pending OAuth sessions are in memory and are lost on restart. Use one application instance or sticky routing while authorizing across replicas. Saved account credentials persist in MySQL.

Refresh, reauthorize, and verify

Access tokens, refresh tokens, account / project identity, and expiry use the existing encrypted credential field and are excluded from provider API responses. When less than one minute remains, the gateway refreshes under a database row lock and saves rotated tokens. Requests and replicas sharing the database reuse the refreshed credential. A refresh failure preserves the stored credential and fails the request.

For expired, revoked, or replacement authorization, edit the existing channel, choose Restart official account sign-in, and save after completion to retain the channel ID and bindings. This feature requires no new schema migration or background service. Verify live sign-in, account eligibility, upstream availability, and inference in your deployment.

Match capabilities and procedures to your deployment version. Read the documentation scope

BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free