From 340d2b6de08a94fa7335b6be8dd973be000e259a Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Tue, 19 May 2026 22:28:26 -0700 Subject: [PATCH] docs(xai-oauth): note X Premium+ also unlocks Grok OAuth (#29055) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The xAI Grok OAuth page only mentioned SuperGrok subscribers. An X Premium+ subscription on the X account you sign in with also unlocks Grok access via accounts.x.ai (xAI links the X subscription status to the xAI session automatically — see https://docs.x.ai/grok/faq). Updates the OAuth page title, prereqs, and overview table, plus the provider/configuration/x-search docs that reference the OAuth flow. --- website/docs/guides/xai-grok-oauth.md | 24 +++++++++++--------- website/docs/integrations/providers.md | 2 +- website/docs/user-guide/configuration.md | 4 ++-- website/docs/user-guide/features/x-search.md | 2 +- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/website/docs/guides/xai-grok-oauth.md b/website/docs/guides/xai-grok-oauth.md index 6719a14a90b..df313e9afa7 100644 --- a/website/docs/guides/xai-grok-oauth.md +++ b/website/docs/guides/xai-grok-oauth.md @@ -1,12 +1,14 @@ --- sidebar_position: 16 -title: "xAI Grok OAuth (SuperGrok Subscription)" -description: "Sign in with your SuperGrok subscription to use Grok models in Hermes Agent — no API key required" +title: "xAI Grok OAuth (SuperGrok / X Premium+)" +description: "Sign in with your SuperGrok or X Premium+ subscription to use Grok models in Hermes Agent — no API key required" --- -# xAI Grok OAuth (SuperGrok Subscription) +# xAI Grok OAuth (SuperGrok / X Premium+) -Hermes Agent supports xAI Grok through a browser-based OAuth login flow against [accounts.x.ai](https://accounts.x.ai), using your existing **SuperGrok subscription**. No `XAI_API_KEY` is required — log in once and Hermes automatically refreshes your session in the background. +Hermes Agent supports xAI Grok through a browser-based OAuth login flow against [accounts.x.ai](https://accounts.x.ai), using either a **SuperGrok subscription** ([grok.com](https://x.ai/grok)) or an **X Premium+ subscription** (linked X account). No `XAI_API_KEY` is required — log in once and Hermes automatically refreshes your session in the background. + +When you sign in with an X account that has Premium+, xAI automatically links the subscription status to your xAI session, so the OAuth flow works the same as it does for direct SuperGrok subscribers. The transport reuses the `codex_responses` adapter (xAI exposes a Responses-style endpoint), so reasoning, tool-calling, streaming, and prompt caching work without any adapter changes. @@ -17,20 +19,20 @@ The same OAuth bearer token is also reused by every direct-to-xAI surface in Her | Item | Value | |------|-------| | Provider ID | `xai-oauth` | -| Display name | xAI Grok OAuth (SuperGrok Subscription) | +| Display name | xAI Grok OAuth (SuperGrok / X Premium+) | | Auth type | Browser OAuth 2.0 PKCE (loopback callback) | | Transport | xAI Responses API (`codex_responses`) | | Default model | `grok-4.3` | | Endpoint | `https://api.x.ai/v1` | | Auth server | `https://accounts.x.ai` | | Requires env var | No (`XAI_API_KEY` is **not** used for this provider) | -| Subscription | [SuperGrok](https://x.ai/grok) — see note below | +| Subscription | [SuperGrok](https://x.ai/grok) or [X Premium+](https://x.com/i/premium_sign_up) — see note below | ## Prerequisites - Python 3.9+ - Hermes Agent installed -- An active SuperGrok subscription on your xAI account +- An active **SuperGrok** subscription on your xAI account, **or** an **X Premium+** subscription on the X account you sign in with (xAI links the subscription automatically) - A browser available on the local machine (or use `--no-browser` for remote sessions) :::warning xAI may restrict OAuth API access by tier @@ -42,7 +44,7 @@ xAI's backend enforces its own allowlist on the OAuth API surface and has been s ```bash # Launch the provider and model picker hermes model -# → Select "xAI Grok OAuth (SuperGrok Subscription)" from the provider list +# → Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list # → Hermes opens your browser to accounts.x.ai # → Approve access in the browser # → Pick a model (grok-4.3 is at the top) @@ -111,7 +113,7 @@ The `◆ Auth Providers` section will show the current state of every provider, ```bash hermes model -# → Select "xAI Grok OAuth (SuperGrok Subscription)" +# → Select "xAI Grok OAuth (SuperGrok / X Premium+)" # → Pick from the model list (grok-4.3 is pinned to the top) ``` @@ -155,7 +157,7 @@ hermes tools # → Text-to-Speech → "xAI TTS" # → Image Generation → "xAI Grok Imagine (image)" # → Video Generation → "xAI Grok Imagine" -# → X (Twitter) Search → "xAI Grok OAuth (SuperGrok Subscription)" +# → X (Twitter) Search → "xAI Grok OAuth (SuperGrok / X Premium+)" ``` If OAuth tokens are already stored, the picker confirms it and skips the credential prompt. If neither OAuth nor `XAI_API_KEY` is set, the picker offers a 3-choice menu: OAuth login, paste API key, or skip. @@ -165,7 +167,7 @@ The `video_gen` toolset is disabled by default. Enable it in `hermes tools` → ::: :::note X search auto-enables when xAI credentials are present -The `x_search` toolset auto-enables whenever xAI credentials (a SuperGrok OAuth token or `XAI_API_KEY`) are configured. Disable explicitly via `hermes tools` → `🐦 X (Twitter) Search` (press space) if you don't want this. The tool routes through xAI's built-in `x_search` Responses API — it works with **either** your SuperGrok OAuth login or a paid `XAI_API_KEY`, and prefers OAuth when both are configured (uses your subscription quota instead of API spend). The tool schema is hidden from the model when no xAI credentials are configured, regardless of whether the toolset is enabled. +The `x_search` toolset auto-enables whenever xAI credentials (a SuperGrok / X Premium+ OAuth token or `XAI_API_KEY`) are configured. Disable explicitly via `hermes tools` → `🐦 X (Twitter) Search` (press space) if you don't want this. The tool routes through xAI's built-in `x_search` Responses API — it works with **either** your SuperGrok / X Premium+ OAuth login or a paid `XAI_API_KEY`, and prefers OAuth when both are configured (uses your subscription quota instead of API spend). The tool schema is hidden from the model when no xAI credentials are configured, regardless of whether the toolset is enabled. ::: ### Models diff --git a/website/docs/integrations/providers.md b/website/docs/integrations/providers.md index 345d50868ae..6969bcc7e60 100644 --- a/website/docs/integrations/providers.md +++ b/website/docs/integrations/providers.md @@ -347,7 +347,7 @@ When using the Z.AI / GLM provider, Hermes automatically probes multiple endpoin xAI is wired through the Responses API (`codex_responses` transport) for automatic reasoning support on Grok 4 models — no `reasoning_effort` parameter needed, the server reasons by default. Set `XAI_API_KEY` in `~/.hermes/.env` and pick xAI in `hermes model`, or drop `grok` as a shortcut into `/model grok-4-1-fast-reasoning`. -SuperGrok subscribers can sign in with browser OAuth instead of using an API key — pick **xAI Grok OAuth (SuperGrok Subscription)** in `hermes model`, or run `hermes auth add xai-oauth`. The same OAuth bearer token is automatically reused by direct-to-xAI tools (TTS, image gen, video gen, transcription). See the [xAI Grok OAuth guide](../guides/xai-grok-oauth.md) for the full flow — and if Hermes runs on a remote host, also see [OAuth over SSH / Remote Hosts](../guides/oauth-over-ssh.md) for the required `ssh -L` tunnel. +SuperGrok and X Premium+ subscribers can sign in with browser OAuth instead of using an API key — pick **xAI Grok OAuth (SuperGrok Subscription)** in `hermes model`, or run `hermes auth add xai-oauth`. The same OAuth bearer token is automatically reused by direct-to-xAI tools (TTS, image gen, video gen, transcription). See the [xAI Grok OAuth guide](../guides/xai-grok-oauth.md) for the full flow — and if Hermes runs on a remote host, also see [OAuth over SSH / Remote Hosts](../guides/oauth-over-ssh.md) for the required `ssh -L` tunnel. When using xAI as a provider (any base URL containing `x.ai`), Hermes automatically enables prompt caching by sending the `x-grok-conv-id` header with every API request. This routes requests to the same server within a conversation session, allowing xAI's infrastructure to reuse cached system prompts and conversation history. diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index 40f924aa209..61fde178737 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -836,7 +836,7 @@ Available providers for auxiliary tasks: `auto`, `main`, plus any provider in th ::: :::tip xAI Grok OAuth -`xai-oauth` logs in via browser OAuth for SuperGrok subscribers (no API key needed). Run `hermes model` and select **xAI Grok OAuth (SuperGrok Subscription)** to authenticate. The same OAuth token is reused for every direct-to-xAI surface (chat, auxiliary tasks, TTS, image gen, video gen, transcription). See the [xAI Grok OAuth guide](../guides/xai-grok-oauth.md), and if Hermes is on a remote host see [OAuth over SSH / Remote Hosts](../guides/oauth-over-ssh.md). +`xai-oauth` logs in via browser OAuth for SuperGrok and X Premium+ subscribers (no API key needed). Run `hermes model` and select **xAI Grok OAuth (SuperGrok Subscription)** to authenticate. The same OAuth token is reused for every direct-to-xAI surface (chat, auxiliary tasks, TTS, image gen, video gen, transcription). See the [xAI Grok OAuth guide](../guides/xai-grok-oauth.md), and if Hermes is on a remote host see [OAuth over SSH / Remote Hosts](../guides/oauth-over-ssh.md). ::: :::warning `"main"` is for auxiliary tasks only @@ -962,7 +962,7 @@ These options apply to **auxiliary task configs** (`auxiliary:`, `compression:`, | `"nous"` | Force Nous Portal | `hermes auth` | | `"codex"` | Force Codex OAuth (ChatGPT account). Supports vision (gpt-5.3-codex). | `hermes model` → Codex | | `"minimax-oauth"` | Force MiniMax OAuth (browser login, no API key). Uses MiniMax-M2.7-highspeed for auxiliary tasks. | `hermes model` → MiniMax (OAuth) | -| `"xai-oauth"` | Force xAI Grok OAuth (browser login for SuperGrok subscribers, no API key). Same OAuth token covers chat, TTS, image, video, and transcription. | `hermes model` → xAI Grok OAuth (SuperGrok Subscription) | +| `"xai-oauth"` | Force xAI Grok OAuth (browser login for SuperGrok or X Premium+ subscribers, no API key). Same OAuth token covers chat, TTS, image, video, and transcription. | `hermes model` → xAI Grok OAuth (SuperGrok Subscription) | | `"main"` | Use your active custom/main endpoint. This can come from `OPENAI_BASE_URL` + `OPENAI_API_KEY` or from a custom endpoint saved via `hermes model` / `config.yaml`. Works with OpenAI, local models, or any OpenAI-compatible API. **Auxiliary tasks only — not valid for `model.provider`.** | Custom endpoint credentials + base URL | Direct API-key providers from the main provider catalog also work here when you want side tasks to bypass your default router. `gmi` is valid once `GMI_API_KEY` is configured: diff --git a/website/docs/user-guide/features/x-search.md b/website/docs/user-guide/features/x-search.md index f241c808f17..49479fbf6f2 100644 --- a/website/docs/user-guide/features/x-search.md +++ b/website/docs/user-guide/features/x-search.md @@ -17,7 +17,7 @@ The `x_search` tool lets the agent search X (Twitter) posts, profiles, and threa | Credential | Source | Setup | |------------|--------|-------| -| **SuperGrok OAuth** (preferred) | Browser login at `accounts.x.ai`, refreshed automatically | `hermes auth add xai-oauth` — see [xAI Grok OAuth (SuperGrok Subscription)](../../guides/xai-grok-oauth.md) | +| **SuperGrok / X Premium+ OAuth** (preferred) | Browser login at `accounts.x.ai`, refreshed automatically | `hermes auth add xai-oauth` — see [xAI Grok OAuth (SuperGrok / X Premium+)](../../guides/xai-grok-oauth.md) | | **`XAI_API_KEY`** | Paid xAI API key | Set in `~/.hermes/.env` | Both hit the same endpoint with the same payload — the only difference is the bearer token. **When both are configured, SuperGrok OAuth wins** so x_search runs against your subscription quota instead of paid API spend.