What Upstream Account Types Does Sub2API Support?

Sub2API supports two fundamental upstream account types: OAuth-based subscription accounts that automatically manage token refresh cycles, and static API-key accounts that pass credentials verbatim to AI providers, alongside provider-specific variants such as Gemini service-account credentials.

Sub2API acts as a unified routing layer for multiple AI providers, abstracting provider credentials into configurable upstream accounts. According to the Wei-Shaw/sub2api source code, these accounts fall into distinct categories designed to accommodate different authentication flows and security requirements, enabling the Multi-Account Management feature highlighted in the repository documentation.

Core Upstream Account Types in Sub2API

The architecture recognizes two primary authentication patterns for routing requests to AI back-ends.

OAuth Subscription Accounts

OAuth accounts implement the PKCE (Proof Key for Code Exchange) flow to obtain and store access_token, refresh_token, and expiry timestamps. When a token nears expiration, Sub2API automatically handles the refresh process without manual intervention. This type supports providers including OpenAI official OAuth, Anthropic via Google OAuth for Claude, xAI Grok OAuth, and Antigravity Claude OAuth.

In backend/internal/service/antigravity_token_provider.go, the GetToken() function extracts the active token from stored OAuth credentials and manages the refresh lifecycle. This implementation ensures that long-running services maintain valid authentication without administrator intervention.

API-Key Accounts

API-key accounts store static credentials that are used verbatim for every request. Unlike OAuth flows, these require no token refresh mechanism or expiry tracking. The same backend/internal/service/antigravity_token_provider.go file handles this via a direct conditional branch: if account.Type == "api_key" returns the stored key immediately. Supported providers include OpenAI, Anthropic, Gemini, xAI, and Antigravity.

Provider-Specific Upstream Account Variants

Beyond the core types, certain providers expose additional credential formats for specialized deployment scenarios.

Gemini Service-Account Credentials

Google Gemini supports a service-account type using JSON-formatted credentials rather than simple API keys. As documented in docs/BATCH_IMAGE_MVP.md, this variant accepts a service_account_json field containing Google Cloud service account keys, enabling authentication for batch processing workloads and enterprise environments.

Grok (xAI) Configuration Flexibility

The Grok provider (xAI) uniquely accepts both OAuth subscription accounts and standard API-key accounts within the same platform configuration. This dual support offers deployment flexibility depending on whether you require managed token refresh for user-delegated access or static credential management for server-to-server authentication.

Creating Upstream Accounts via the Admin CLI

Sub2API provides the sub2api-admin.js CLI tool located at skills/sub2api-admin/scripts/sub2api-admin.js to provision accounts. Alternatively, you can use the REST admin API endpoint POST /api/v1/admin/accounts to create upstream accounts programmatically.

Creating an OAuth subscription account:

node scripts/sub2api-admin.js accounts create \
  --json '{
    "name": "my-openai-oauth",
    "platform": "openai",
    "type": "oauth",
    "credentials": {
      "client_id": "...",
      "client_secret": "...",
      "redirect_uri": "http://localhost:8080/callback",
      "scope": "openid profile email offline_access",
      "auth_url": "https://auth.openai.com/oauth2/authorize",
      "token_url": "https://auth.openai.com/oauth2/token"
    }
  }'

Creating a static API-key account:

node scripts/sub2api-admin.js accounts create \
  --json '{
    "name": "my-openai-apikey",
    "platform": "openai",
    "type": "api_key",
    "api_key": "sk-XXXXXXXXXXXXXXXXXXXXXXXX"
  }'

Creating a Gemini service-account:

node scripts/sub2api-admin.js accounts create \
  --json '{
    "name": "my-gemini-sa",
    "platform": "gemini",
    "type": "service_account",
    "service_account_json": "{ \"type\": \"service_account\", \"project_id\": \"…\", \"private_key\": \"…\" }"
  }'

As detailed in docs/COMPOSITE_GROUPS.md, these upstream accounts of varying types can be organized into composite groups for load balancing and failover scenarios across different providers.

Summary

• Sub2API supports OAuth subscription accounts with automatic token refresh via PKCE flow, and API-key accounts using static credentials that require no refresh.
• OAuth token management is implemented in backend/internal/service/antigravity_token_provider.go via the GetToken() function.
• Gemini offers a third variant: service-account JSON credentials for Google Cloud authentication, documented in docs/BATCH_IMAGE_MVP.md.
• The skills/sub2api-admin/scripts/sub2api-admin.js CLI and POST /api/v1/admin/accounts REST endpoint enable programmatic creation of all supported upstream account types.
• The Multi-Account Management system explicitly categorizes these types to enable flexible routing across OpenAI, Anthropic, xAI, Antigravity, and Gemini backends.

Frequently Asked Questions

What upstream account types does Sub2API support?

Sub2API supports two primary upstream account types: OAuth-based subscription accounts for providers like OpenAI and Anthropic that handle automatic token refresh, and static API-key accounts that pass credentials directly without refresh logic. Additionally, Gemini supports a service-account type using JSON credentials.

How does Sub2API handle authentication for OAuth upstream accounts?

According to the source code in backend/internal/service/antigravity_token_provider.go, Sub2API stores access tokens, refresh tokens, and expiry timestamps obtained via the PKCE flow. The GetToken() function automatically refreshes expired tokens before routing requests to the provider, ensuring continuous service availability.

Can I use Google Cloud service accounts with Sub2API?

Yes. Beyond standard API keys, Sub2API supports Gemini service-account credentials as documented in docs/BATCH_IMAGE_MVP.md. You create these by setting "type": "service_account" and providing the JSON credential object containing the project ID and private key via the admin CLI or REST API.

What is the difference between OAuth and API-key accounts in Sub2API?

OAuth accounts require initial authorization via PKCE flow and automatically manage the token lifecycle including refresh, making them suitable for user-delegated access scenarios. API-key accounts use static strings stored verbatim in antigravity_token_provider.go and require no refresh mechanism, making them ideal for server-to-server authentication where credentials remain constant over time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}