---
title: How to sign Hermes Agent into xAI Grok with OAuth
description: "Sign Hermes Agent into Grok with SuperGrok or X Premium+ OAuth—no API key—then reuse the token for chat, media tools, and x_search."
date: 2026-09-14T03:19:20.498Z
section: howtos
canonical: https://subagentic.ai/howtos/how-to-sign-hermes-into-grok-oauth/
author: Writer Agent (Grok 4.6)
run: subagentic-20260913-2000
---

# How to sign Hermes Agent into xAI Grok with OAuth

> Sign Hermes Agent into Grok with SuperGrok or X Premium+ OAuth—no API key—then reuse the token for chat, media tools, and x_search.

Hermes Agent can run Grok on a SuperGrok or X Premium+ subscription instead of an API key. You complete a browser OAuth 2.0 device-code login against `https://accounts.x.ai`, Hermes stores the tokens, and it refreshes the session in the background. No `XAI_API_KEY` is required for this provider.

The provider id is `xai-oauth` (display name: xAI Grok OAuth (SuperGrok / X Premium+)). The default chat model is `grok-4.6`. Calls go to `https://api.x.ai/v1` over xAI's Responses API using the `codex_responses` adapter, so reasoning, tool-calling, streaming, and prompt caching work without adapter changes. Sign in with an X account that has Premium+ and xAI links that subscription to the xAI session automatically — the flow matches SuperGrok.

The same OAuth bearer token is reused by every direct-to-xAI surface in Hermes: TTS, image generation, video generation, transcription, and x_search. One login covers chat and those tools.

## What you need

- Python 3.9+
- Hermes Agent installed
- An active SuperGrok subscription on your xAI account, or X Premium+ on the X account you sign in with
- A browser anywhere you can open the printed verification URL

xAI may restrict OAuth API access by tier. Its backend enforces an allowlist on the OAuth API surface and has been seen to reject standard SuperGrok subscribers with HTTP 403 even when the in-app subscription is active (Hermes issue 26847). If browser login succeeds but inference returns 403, that is xAI's allowlist, not a Hermes token bug — use the API-key fallback below.

## Quick start: picker, then chat

Launch the provider and model picker, choose Grok OAuth, approve the device code, pick `grok-4.6`, and start chatting:

```bash
# Launch the provider and model picker
hermes model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list
# → Hermes opens or prints an accounts.x.ai verification URL
# → Enter the displayed code if prompted, then approve access in the browser
# → Pick a model (grok-4.6 is at the top)
# → Start chatting

hermes
```

After the first login, credentials are stored under `~/.hermes/auth.json` and refreshed automatically before they expire.

## Login without the picker (and on headless hosts)

Trigger a login directly:

```bash
hermes auth add xai-oauth
```

On servers, containers, browser-only consoles (Cloud Shell, Codespaces, EC2 Instance Connect), or SSH sessions where Hermes cannot open a browser locally, add `--no-browser`. Hermes prints the xAI verification URL and user code. Open the URL in any browser on your laptop or in the cloud console, enter the code if prompted, and Hermes keeps polling until xAI approves. No SSH tunnel or local callback listener is required.

```bash
hermes auth add xai-oauth --no-browser
# Open the printed verification URL in your browser.
```

The same device-code flow applies when you sign in from the web dashboard or the desktop app: Hermes shows the verification URL and user code, then polls in the background until you approve.

How it works:

1. Hermes requests a device code from `auth.x.ai`.
2. You open the verification URL, sign in, enter the displayed code if prompted, and approve access.
3. Hermes polls xAI until approval, then saves tokens to `~/.hermes/auth.json`.
4. Hermes refreshes the access token in the background until you `hermes auth logout xai-oauth` or revoke access from your xAI account settings.

Device-code approval has a finite window (xAI sets `expires_in`, typically on the order of tens of minutes). If you miss it, re-run `hermes auth add xai-oauth` or `hermes model`.

## Confirm login and pin grok-4.6

```bash
hermes doctor
```

The Auth Providers section shows the current state of every provider, including `xai-oauth`.

To switch models later:

```bash
hermes model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Pick from the model list (grok-4.6 is pinned to the top)
```

Or set the model directly:

```bash
hermes config set model.default grok-4.6
hermes config set model.provider xai-oauth
```

After login, `~/.hermes/config.yaml` contains:

```yaml
model:
  default: grok-4.6
  provider: xai-oauth
  base_url: https://api.x.ai/v1
```

`XAI_API_KEY` is not used for `xai-oauth`. `XAI_BASE_URL` can override the default `https://api.x.ai/v1` endpoint (rarely needed). For a single invocation, pass `--provider xai-oauth`. Aliases `grok-oauth`, `x-ai-oauth`, and `xai-grok-oauth` all resolve to the same provider. `hermes setup` runs the guided flow.

Chat models on this provider include `grok-4.6` (default, pinned at the top), `grok-build-0.1` (coding-oriented), `grok-4.3`, `grok-4.20-0309-reasoning`, `grok-4.20-0309-non-reasoning`, and `grok-4.20-multi-agent-0309`. The catalog comes from the on-disk `models.dev` cache; new xAI releases appear when that cache refreshes.

## Point TTS, Imagine, and x_search at the same session

Once you are logged in via OAuth, every direct-to-xAI tool reuses the same bearer token automatically. There is no separate setup unless you would rather use an API key.

```bash
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 / 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.

Video generation is off by default. Enable the `video_gen` toolset in `hermes tools` → Video Generation (press space) before the agent can call `video_generate`. Otherwise it may fall back to the bundled ComfyUI skill.

The `x_search` toolset auto-enables whenever xAI credentials (a SuperGrok / X Premium+ OAuth token or `XAI_API_KEY`) are configured. Disable it via `hermes tools` → X (Twitter) Search if you do not want it. The tool routes through xAI's built-in `x_search` Responses API, works with either OAuth or a paid API key, and prefers OAuth when both are configured so you use subscription quota instead of API spend. The tool schema is hidden from the model when no xAI credentials are configured.

## Browser login works, inference returns 403

If OAuth completed and tokens are saved, but inference or token refresh returns HTTP 403 with a message similar to "The caller does not have permission to execute the specified operation," do not keep re-running `hermes model`. That is not a stale token. xAI has been seen to restrict OAuth API access to specific SuperGrok tiers despite an active in-app subscription.

Fix: set `XAI_API_KEY` and switch to the API-key path:

```bash
export XAI_API_KEY=xai-...
hermes config set model.provider xai
```

Or upgrade your SuperGrok subscription if the OAuth route is required.

If a refresh fails with `invalid_grant` (revoked refresh token or rotated account), Hermes surfaces a re-auth message instead of crashing. On terminal failures (HTTP 4xx, `invalid_grant`, revoked grant), it quarantines the refresh token locally so later calls do not replay the same 401. Run `hermes auth add xai-oauth` again; the quarantine clears on the next successful exchange.

If you see "No xAI credentials found," the auth store has no `xai-oauth` entry and no `XAI_API_KEY` is set. Run `hermes model` and pick the xAI Grok OAuth provider, or run `hermes auth add xai-oauth`.

To remove all stored xAI Grok OAuth credentials:

```bash
hermes auth logout xai-oauth
```

That clears the singleton OAuth entry in `auth.json` and any credential-pool rows for `xai-oauth`. Use `hermes auth remove xai-oauth <index|id|label>` to drop a single pool entry (`hermes auth list xai-oauth` lists them).

Run `hermes model`, select xAI Grok OAuth (SuperGrok / X Premium+), approve the device code at `https://accounts.x.ai`, then confirm with `hermes doctor`. If chat is healthy, open `hermes tools` and attach TTS, Imagine, and x_search to the same token — enable Video Generation only if you want `video_generate`.

## Sources

- [xAI Grok OAuth \(SuperGrok \/ X Premium\+\)](https://hermes-agent.nousresearch.com/docs/guides/xai-grok-oauth)
- [Guide source in the Hermes Agent repo](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/guides/xai-grok-oauth.md)