# What Upstream Account Types Does Sub2API Support?

> Discover Sub2API upstream account types. It supports OAuth subscriptions, static API keys, and Gemini service accounts for seamless AI provider integration.

- Repository: [Wesley Liddick/sub2api](https://github.com/Wei-Shaw/sub2api)
- Tags: api-reference
- Published: 2026-08-23

---

**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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/sub2api-admin.js) CLI tool located at [`skills/sub2api-admin/scripts/sub2api-admin.js`](https://github.com/Wei-Shaw/sub2api/blob/main/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:**

```bash
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:**

```bash
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:**

```bash
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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/docs/BATCH_IMAGE_MVP.md).
- The [`skills/sub2api-admin/scripts/sub2api-admin.js`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/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`](https://github.com/Wei-Shaw/sub2api/blob/main/antigravity_token_provider.go) and require no refresh mechanism, making them ideal for server-to-server authentication where credentials remain constant over time.