[Feature Request] Add xAI Grok OAuth (SuperGrok / X Premium+) provider for Grok Build / grok-build-0.1 access

[apoapostolov]

[Feature Request] Add xAI Grok OAuth (SuperGrok / X Premium+) provider for Grok Build / grok-build-0.1 access

Summary

OmniRoute currently supports Grok access primarily through the grok-web web cookie provider (using the sso cookie from grok.com / x.ai web UI).

xAI now offers SuperGrok and SuperGrok Heavy subscription tiers (alongside X Premium+) that unlock Grok Build — a dedicated terminal coding agent — and higher-performance models via a first-class OAuth authentication flow against accounts.x.ai.

This OAuth method is already implemented and in active use in several major tools:

• Hermes Agent — native xai-oauth / grok-oauth provider (browser PKCE login, auto-refresh)
• OpenCode — /connect → "xAI Grok OAuth (SuperGrok Subscription)"
• Official Grok Build CLI (https://x.ai/cli)

The OAuth path gives access to subscription-backed models and capabilities (including grok-build-0.1 and advanced Grok 4 variants with reasoning/multi-agent modes) that go beyond what the cookie-based web wrapper or standard xAI API keys provide for coding/agent use cases.

Proposed Feature

Add a new OAuth provider in OmniRoute:

• Provider ID(s): xai-oauth, grok-oauth, xai-grok-oauth (with aliases)
• Category: OAuth Providers (like codex, claude, github, cline, kilocode, etc.)
• Auth mechanism: Browser-based OAuth 2.0 PKCE with loopback callback (or device code / manual paste for headless/remote)
• Target: https://accounts.x.ai for login + token issuance
• Upstream endpoint(s): https://api.x.ai/v1 (and/or the specific Responses API / codex_responses transport used by Grok Build agents)
• Models exposed: grok-build-0.1, grok-4.3, reasoning variants (grok-4.20-*-reasoning), image/video/grok-imagine models, etc. (dynamically from catalog where possible)
• Subscription awareness: Note tier differences (standard SuperGrok vs SuperGrok Heavy) where rate limits / model access differ

This should live alongside (not replace) the existing grok-web cookie provider, as they serve slightly different access patterns and user bases.

Why This Matters for OmniRoute

• Unified gateway value: Users who already pay for SuperGrok/Heavy can route that high-quality subscription capacity through OmniRoute's single OpenAI-compatible endpoint (http://127.0.0.1:20128/v1).
• CLI tool coverage: Immediately benefits all tools that OmniRoute supports (OpenCode, Claude Code, Codex, Cline, Kilo Code, Continue, Hermes itself, etc.) without each tool needing separate native xAI OAuth wiring.
• Combos & resilience: Combine the SuperGrok OAuth connection with other cheap/fast providers using OmniRoute's 14 routing strategies, fallbacks, circuit breakers, cost tracking, etc.
• Consistency: OmniRoute already excels at OAuth providers for coding agents (Codex, Claude Code, etc.). Adding the official xAI Grok OAuth fits the existing pattern perfectly.
• Free-tier / OAuth expansion: Aligns with the "50+ free tiers / OAuth providers" positioning.

References & Prior Art

• Hermes Agent official guide: https://hermes-agent.nousresearch.com/docs/guides/xai-grok-oauth
• xAI announcements:
  • https://x.ai/news/grok-opencode (OpenCode integration)
  • https://x.ai/news/grok-build-cli (standalone Grok Build CLI)
• Related implementation discussions in Hermes repo (example): xAI OAuth/SuperGrok Responses API rejects replayed encrypted reasoning — 400 on every multi-turn tool call (regression from b4afc6546) NousResearch/hermes-agent#30310
• Current OmniRoute Grok Web cookie support: see discussions successfuly fixed grok web! #1651, Guide on how to get cookies for ChatGPT Web, Grok Web, Perplexity Web, Blackbox Web #2200 and grok-web entry in providers.
• Provider definition file: src/shared/constants/providers.ts (OAUTH_PROVIDERS section)

Suggested Implementation Approach

1. Add entry to OAUTH_PROVIDERS + risk notices (subscriptionRisk: true).
2. Implement auth executor / token manager (reuse/refine the recent v3.8.4 OAuth refresh fixes).
3. Add dashboard "Sign in with xAI / SuperGrok" flow (browser launch or manual URL + callback paste for remote).
4. Update model catalog / pricing for the new models (or mark as dynamic).
5. Add to CLI tool detection if needed for auto-config of OpenCode / Hermes / etc.
6. Documentation + wiki updates (Provider Reference, etc.).
7. Optional: support for multiple xAI OAuth accounts + proxy-per-connection (as done for other multi-account web/OAuth providers).

Additional Notes

• Some SuperGrok tiers may have restrictions (e.g. 403 on certain endpoints for non-Heavy); the implementation should surface clear errors and guidance (similar to Hermes warnings).
• Token storage should follow OmniRoute's existing secure patterns (SQLite + encryption).
• Headless/remote support (SSH port-forward, manual-paste) is highly desirable, matching Hermes and OpenCode UX.

I (and the Hermes community) would be happy to collaborate on the spec, provide token examples, test builds, or review PRs. This is a high-leverage feature for anyone already subscribed to SuperGrok who wants to use OmniRoute as their central router.

Thanks for the incredible work on OmniRoute — it already makes the fragmented AI tool landscape much more manageable.

[diegosouzapw]

Hi @apoapostolov! Thanks for the great feature suggestion! 🙏

We've analyzed your request — it aligns with OmniRoute's roadmap and we have a clear implementation path:

First-class xai-oauth/grok-oauth provider using OAuth 2.0 PKCE against accounts.x.ai, with device-code/manual-paste fallback for headless setups, embedded public client_id/secret via resolvePublicCred() extracted from the official Grok Build CLI / Hermes / OpenCode sources, exposing grok-build-0.1 and the SuperGrok-tier reasoning variants alongside the existing grok-web cookie provider.

We've cataloged it internally and it will be picked up in an upcoming release.

Status: ✅ Accepted — cataloged for future implementation

We'll respond here and tag you once the implementation lands so you can test it before it ships.

Closing for now to keep our open-issue list focused on items still awaiting input. The feature is tracked in our internal backlog and won't be forgotten.

Thank you for helping improve OmniRoute! 🚀