hermes - 💡(How to fix) Fix [Bug]: xAI OAuth (xai-oauth) returns HTTP 403 for standard SuperGrok subscribers — backend enforcing Heavy-only despite docs claiming all tiers

Summary

The xai-oauth provider, introduced alongside the Grok/Hermes integration announcement on 2026-05-15, consistently returns HTTP 403 for users with a standard SuperGrok subscription ($30/month). The OAuth login flow and token storage work correctly — the failure is on xAI's backend at inference time. The xAI dashboard confirms the issue: API access is currently gated to SuperGrok Heavy only, contradicting both the xAI announcement and the Hermes documentation.

Note to maintainers: This appears to be a misconfiguration on xAI's backend — the Hermes-side implementation looks correct. Flagging here so NousResearch can escalate directly to xAI and update docs/error messaging in the interim.

Environment

Steps to Reproduce

1. Have an active standard SuperGrok subscription (not Heavy)
2. Run hermes auth add xai-oauth — browser OAuth flow completes successfully
3. Verify tokens are saved: ~/.hermes/auth.json contains a valid xai-oauth block with access_token, refresh_token, id_token, and active_provider: "xai-oauth"
4. Start a chat session via hermes --tui with xai-oauth as the active provider
5. Send any message

Expected Behavior

Per the xAI announcement ("available on every tier") and Hermes docs ("SuperGrok — any active tier"), inference should succeed and return a Grok response.

Actual Behavior

Every message is rejected with: ⚠️ Non-retryable error (HTTP 403) ❌ Non-retryable error (HTTP 403): HTTP 403: Error code: 403 - {'code': 'The caller does not have permission to execute the specified operation', 'error': 'You have either run out of available resources or do not have an active Grok subscription. Manage your subscription at https://grok.com/?_s=usage or subscribe at https://grok.com/supergrok.'} — xAI rejected this OAuth account. NOTE: X Premium+ does NOT include xAI API access — only standalone SuperGrok subscribers can use this provider.

Root Cause (hypothesis)

The OAuth endpoint used by Hermes appears to route through the same backend surface as Grok Build (xAI's new coding agent CLI), which xAI has locked to SuperGrok Heavy subscribers only. Visiting https://grok.com/?_s=usage with a standard SuperGrok account confirms this — the dashboard displays: Grok Build Beta Beta is only available for SuperGrok Heavy users. Upgrade and start using your free credits included.

xAI's permission layer appears to be checking for Heavy-tier entitlements on the OAuth inference endpoint, even though the intended behavior per published docs is to allow all paid SuperGrok tiers.

What Works / What Doesn't

Workaround

Using XAI_API_KEY with the xai provider instead of xai-oauth works correctly:

# add to ~/.hermes/.env
XAI_API_KEY=xai-...
# then run hermes model and select "xAI" (not "xAI Grok OAuth")

Suggested Actions

1. Escalate to xAI: The fix needs to happen on xAI's backend — their permission layer needs to grant standard SuperGrok OAuth tokens access to the inference endpoint, not just Heavy tokens.
2. Improve the 403 error message: The current in-TUI note says "X Premium+ does NOT include xAI API access" — this is slightly misleading for users who have standard SuperGrok (which also hits this 403). Suggest mentioning the XAI_API_KEY workaround explicitly.
3. Add a fallback hint: When xai-oauth returns 403, Hermes could proactively suggest switching to XAI_API_KEY with a link to console.x.ai.

Additional Context

• Integration announced: 2026-05-15 — this is a day-one issue
• Tried: multiple fresh OAuth re-authentications, gateway restarts, full process kills, env var overrides — all produce the same 403
• The xAI announcement page (https://x.ai/news/grok-hermes) still says "every tier" as of 2026-05-16

Debug Report

• Report: https://paste.rs/Lj8D4
• agent.log: https://paste.rs/9UYa2
• gateway.log: https://paste.rs/sfkxr

Note: pastes auto-delete after 6 hours.