Skip to main content

xAI Grok OAuth (SuperGrok / X Premium+)

VibeOS supports xAI Grok through a browser-based OAuth login flow against accounts.x.ai, using either a SuperGrok subscription (grok.com) or an X Premium+ subscription (linked X account). No XAI_API_KEY is required — log in once and VibeOS 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.

The same OAuth bearer token is also reused by every direct-to-xAI surface in VibeOS — TTS, image generation, video generation, and transcription — so a single login covers all four.

Overview​

ItemValue
Provider IDxai-oauth
Display namexAI Grok OAuth (SuperGrok / X Premium+)
Auth typeBrowser OAuth 2.0 PKCE (loopback callback)
TransportxAI Responses API (codex_responses)
Default modelgrok-build-0.1
Endpointhttps://api.x.ai/v1
Auth serverhttps://accounts.x.ai
Requires env varNo (XAI_API_KEY is not used for this provider)
SubscriptionSuperGrok or X Premium+ — see note below

Prerequisites​

  • Python 3.9+
  • VibeOS installed
  • 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)
xAI may restrict OAuth API access by tier

xAI's backend enforces its own allowlist on the OAuth API surface and has been seen to reject standard SuperGrok subscribers with HTTP 403 (see issue #26847) even though the in-app subscription is active. If OAuth login succeeds in the browser but inference returns 403, set XAI_API_KEY and switch to the API-key path (provider: xai) — that surface is not subject to the same gating today.

Quick Start​

# Launch the provider and model picker
vibeos model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list
# → VibeOS opens your browser to accounts.x.ai
# → Approve access in the browser
# → Pick a model (grok-build-0.1 is at the top)
# → Start chatting

vibeos

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

Logging In Manually​

You can trigger a login without going through the model picker:

vibeos auth add xai-oauth

Remote / headless sessions​

On servers, containers, or SSH sessions where no browser is available, VibeOS detects the remote environment and prints the authorization URL instead of opening a browser.

Important: the loopback listener still runs on the remote machine at 127.0.0.1:56121. The xAI redirect needs to reach that listener, so opening the URL on your laptop will fail (Could not establish connection. We couldn't reach your app.) unless you forward the port:

# In a separate terminal on your local machine:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Then in your SSH session on the remote machine:
vibeos auth add xai-oauth --no-browser
# Open the printed authorize URL in your local browser.

Through a jump box / bastion: add -J jump-user@jump-host.

See OAuth over SSH / Remote Hosts for the full step-by-step, including ProxyJump chains, mosh/tmux, and ControlMaster gotchas.

Browser-only remotes (Cloud Shell, Codespaces, EC2 Instance Connect)​

If you don't have a regular SSH client (e.g. you're running VibeOS inside GCP Cloud Shell, GitHub Codespaces, AWS EC2 Instance Connect, Gitpod, or another browser-based console), the ssh -L recipe above isn't available. Use --manual-paste instead — VibeOS skips the loopback listener and lets you paste the failed callback URL straight from your browser:

vibeos auth add xai-oauth --manual-paste
# Or via the model picker:
vibeos model --manual-paste

See OAuth over SSH / Remote Hosts for the full walkthrough. Regression fix for #26923.

If the consent page renders the authorization code directly on the page (xAI's current behavior on browser-based consoles) instead of redirecting to your 127.0.0.1:56121/callback, paste just the bare code value at the Callback URL: prompt — VibeOS accepts the full URL, a bare ?code=...&state=... query fragment, or a bare code interchangeably.

How the Login Works​

  1. VibeOS opens your browser to accounts.x.ai.
  2. You sign in (or confirm your existing session) and approve access.
  3. xAI redirects back to VibeOS and the tokens are saved to ~/.vibeos/auth.json.
  4. From then on, VibeOS refreshes the access token in the background — you stay signed in until you vibeos auth logout xai-oauth or revoke access from your xAI account settings.

Checking Login Status​

vibeos doctor

The ◆ Auth Providers section will show the current state of every provider, including xai-oauth.

Switching Models​

vibeos model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Pick from the model list (grok-build-0.1 is pinned to the top)

Or set the model directly:

vibeos config set model.default grok-build-0.1
vibeos config set model.provider xai-oauth

Configuration Reference​

After login, ~/.vibeos/config.yaml will contain:

model:
  default: grok-build-0.1
  provider: xai-oauth
  base_url: https://api.x.ai/v1

Provider aliases​

All of the following resolve to xai-oauth:

vibeos --provider xai-oauth        # canonical
vibeos --provider grok-oauth       # alias
vibeos --provider x-ai-oauth       # alias
vibeos --provider xai-grok-oauth   # alias

Direct-to-xAI Tools (TTS / Image / Video / Transcription / X Search)​

Once you're logged in via OAuth, every direct-to-xAI tool reuses the same bearer token automatically — there is no separate setup unless you'd rather use an API key.

To pick a backend for each tool:

vibeos 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

The video_gen toolset is disabled by default. Enable it in vibeos tools → 🎬 Video Generation (press space) before the agent can call video_generate. Otherwise the agent may fall back to the bundled ComfyUI skill, which is also tagged for video generation.

X search auto-enables when xAI credentials are present

The x_search toolset auto-enables whenever xAI credentials (a SuperGrok / X Premium+ OAuth token or XAI_API_KEY) are configured. Disable explicitly via vibeos 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​

ToolModelNotes
Chatgrok-build-0.1Default; auto-selected when you log in via OAuth
Chatgrok-4.3Previous default
Chatgrok-4.20-0309-reasoningReasoning variant
Chatgrok-4.20-0309-non-reasoningNon-reasoning variant
Chatgrok-4.20-multi-agent-0309Multi-agent variant
Imagegrok-imagine-imageDefault; ~5–10 s
Imagegrok-imagine-image-qualityHigher fidelity; ~10–20 s
Videogrok-imagine-videoText-to-video
Videogrok-imagine-video-1.5-previewImage-to-video; dated alias grok-imagine-video-1.5-2026-05-30
TTS(default voice)xAI /v1/tts endpoint

The chat catalog is derived live from the on-disk models.dev cache; new xAI releases appear automatically once that cache refreshes. grok-build-0.1 is always pinned to the top of the list.

Environment Variables​

VariableEffect
XAI_BASE_URLOverride the default https://api.x.ai/v1 endpoint (rarely needed).

To select xAI as the active provider, set model.provider: xai-oauth in config.yaml (use vibeos setup for the guided flow) or pass --provider xai-oauth for a single invocation.

Troubleshooting​

Token expired — not re-logging in automatically​

VibeOS refreshes the token before each session and again reactively on a 401. If refresh fails with invalid_grant (the refresh token was revoked, or the account was rotated), VibeOS surfaces a typed re-auth message instead of crashing.

When the refresh failure is terminal (HTTP 4xx, invalid_grant, revoked grant, etc.), VibeOS marks the refresh token as dead and quarantines it locally — subsequent calls skip the doomed refresh attempt instead of replaying the same 401 over and over. The agent surfaces a single "re-authentication required" message and stays out of the way until you log in again.

Fix: run vibeos auth add xai-oauth again to start a fresh login. The quarantine clears on the next successful exchange.

Authorization timed out​

The loopback listener has a finite expiry window (default 180 s). If you don't approve the login in time, VibeOS raises a timeout error.

Fix: re-run vibeos auth add xai-oauth (or vibeos model). The flow starts fresh.

State mismatch (possible CSRF)​

VibeOS detected that the state value returned by the authorization server doesn't match what it sent.

Fix: re-run the login. If it persists, check for a proxy or redirect that is modifying the OAuth response.

Logging in from a remote server​

On SSH or container sessions VibeOS prints the authorization URL instead of opening a browser. The loopback callback listener still binds 127.0.0.1:56121 on the remote host — your laptop's browser can't reach it without an SSH local-forward:

# Local machine, separate terminal:
ssh -N -L 56121:127.0.0.1:56121 user@remote-host

# Remote machine:
vibeos auth add xai-oauth --no-browser

Full walkthrough (jump boxes, mosh/tmux, port conflicts): OAuth over SSH / Remote Hosts.

HTTP 403 after a successful login (tier / entitlement)​

OAuth completed in the browser, 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".

This is not a stale-token problem — re-running vibeos model won't change it. xAI's backend has been seen to restrict OAuth API access to specific SuperGrok tiers despite the in-app subscription being active (issue #26847).

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

export XAI_API_KEY=xai-...
vibeos config set model.provider xai

Or upgrade your subscription at x.ai/grok if the OAuth route is required.

"No xAI credentials found" error at runtime​

The auth store has no xai-oauth entry and no XAI_API_KEY is set. You haven't logged in yet, or the credential file was deleted.

Fix: run vibeos model and pick the xAI Grok OAuth provider, or run vibeos auth add xai-oauth.

Logging Out​

To remove all stored xAI Grok OAuth credentials:

vibeos auth logout xai-oauth

This clears both the singleton OAuth entry in auth.json and any credential-pool rows for xai-oauth. Use vibeos auth remove xai-oauth <index|id|label> if you only want to drop a single pool entry (run vibeos auth list xai-oauth to see them).

See Also​