Grok Web vs Grok Console SSO Authentication: What’s the Difference in Grok2API

Grok Web SSO relies on browser-session tokens with Cloudflare clearance and limited OpenAI compatibility, while Grok Console SSO uses dashboard-generated tokens that provide full API functionality, with only unidirectional Web-to-Console sync permitted.

The chenyme/grok2api repository treats Grok Web and Grok Console as distinct upstream account pools, each requiring different SSO authentication methods. Understanding the difference between Grok Web and Grok Console SSO authentication is critical for correctly importing tokens, managing account conversions, and avoiding unsupported API operations.

Credential Types and Authentication Flows

Grok Web SSO (Browser-Based)

Grok Web SSO tokens are generated for the Web product and tied to browser-style sessions including Cloudflare clearance cookies. These tokens typically carry the grok_web: prefix when imported into the system. The Web provider implementation resides in backend/internal/infra/provider/web/sso_build.go, which handles token validation and session management.

Grok Console SSO (Dashboard-Based)

Grok Console SSO tokens are generated for the Console product and map to the official OpenAI-style dashboard API. These tokens use the grok_console: prefix and inherit the full OpenAI-compatible feature set. The Console provider logic lives in backend/internal/infra/provider/console/*, implemented alongside the Build provider but with distinct SSO handling.

Supported Operations and Conversion Rules

The system enforces strict directional rules regarding account conversions and synchronization.

• Web to Build: Supported. You can convert Grok Web accounts to Build accounts using the Web provider utilities.
• Web to Console: Supported one-way only. The system allows syncing Web accounts to Console accounts, but the reverse operation is explicitly blocked.
• Console to Web: Not supported. Attempting this conversion triggers an error message.

In backend/internal/application/account/service.go (around line 859), the conversion validation logic explicitly checks account types:

// Conversion validation - only Web accounts support conversion
if !isWebAccount {
    return fmt.Errorf("仅 Grok Web SSO 账号支持转换")
}

// Sync validation - Web to Console only
if err := syncWebToConsole(account); err != nil {
    return fmt.Errorf("Grok Web 账号同步到 Console 失败")
}

When Console token generation fails, the system returns errors containing "生成 Grok Console SSO 凭据" to distinguish Console-specific credential issues.

Feature Parity and API Limitations

Grok Web Limitations

Grok Web SSO accounts do not support certain OpenAI-style features. According to the implementation in backend/internal/infra/provider/web/tools.go, the Web provider explicitly rejects:

• tools.type
• tool_choice.type
• storage_options
• output.upload_url

These limitations exist because the Web endpoint is designed for browser-based interactions rather than full API compatibility.

Grok Console Capabilities

Grok Console SSO accounts inherit complete OpenAI-compatible functionality because they map directly to the official Console API endpoints. This makes Console SSO preferable for applications requiring full tool use and advanced API features.

Implementation File Structure

The codebase separates these providers into distinct directories with dedicated responsibilities:

Grok Web Provider:

• backend/internal/infra/provider/web/sso_build.go - Handles Web SSO token generation and Build conversion logic
• backend/internal/infra/provider/web/quota.go - Manages quota synchronization and health checks for Web accounts
• backend/internal/infra/provider/web/tools.go - Implements tool handling with explicit feature restrictions

Grok Console Provider:

• backend/internal/infra/provider/console/* - Contains Console-specific SSO handling and token management

Frontend Distinction: The UI separates these account types in frontend/src/features/accounts/accounts-page.tsx, displaying them under distinct tabs using different TabsTrigger values to prevent user confusion between the two credential types.

Practical Code Examples

When importing tokens, the system distinguishes account types by prefix and applies appropriate validation:

// Import handler logic (account/handler.go)
if strings.HasPrefix(token, "grok_web:") {
    // Parse and store as Web account
    // Supports conversion to Build
    // Conversion to Console rejected with:
    // return fmt.Errorf("仅 Grok Web SSO 账号支持转换")
}

if strings.HasPrefix(token, "grok_console:") {
    // Parse and store as Console account
    // Only receives synced data from Web accounts
    // No reverse conversion support
}

Summary

• Grok Web SSO uses browser-based authentication with Cloudflare clearance, supports conversion to Build accounts, and lacks certain OpenAI-compatible features like advanced tool types.
• Grok Console SSO uses dashboard-based tokens, provides full API feature parity, and can only receive one-way sync from Web accounts according to backend/internal/application/account/service.go.
• The two systems are implemented in separate provider directories (web/ vs console/) with distinct validation logic and UI representations.
• Token prefixes (grok_web: vs grok_console:) determine routing and supported operations during the import process.

Frequently Asked Questions

Can I convert a Grok Console SSO account to a Grok Web SSO account?

No, bidirectional conversion is not supported. The codebase in backend/internal/application/account/service.go explicitly blocks Console-to-Web conversion, only allowing Web-to-Console synchronization in one direction. Attempting reverse conversion will fail with validation errors.

Why do Grok Web accounts lack certain OpenAI-compatible features?

Grok Web accounts are designed for browser-based interactions and anti-bot protection. According to the implementation in backend/internal/infra/provider/web/tools.go, features like tools.type, tool_choice.type, and output.upload_url are explicitly rejected because the Web endpoint does not support the full OpenAI API specification used by the Console product.

How does the system distinguish between Web and Console tokens during import?

The system checks token prefixes in the import handlers. Tokens starting with grok_web: are routed to the Web provider implementation, while grok_console: prefixes trigger Console account creation. This routing logic determines which conversion rules and feature sets apply to the imported account.

Where are the conversion and sync rules enforced in the source code?

Conversion rules are enforced in backend/internal/application/account/service.go around line 859, where the code validates that only Web accounts support conversion and manages the one-way sync from Web to Console accounts. The UI separation appears in frontend/src/features/accounts/accounts-page.tsx, which renders distinct tabs for each account type.

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