HeyRocky

Sign In to xAI Grok with OAuth

Hermes can authenticate to xAI through a browser-based device-code flow using an eligible SuperGrok or linked X Premium+ account. The canonical provider ID is xai-oauth; it uses xAI’s Responses-style transport and does not require XAI_API_KEY for the OAuth route.

A successful browser login does not guarantee inference entitlement. The official guide notes that xAI may return HTTP 403 for some subscription tiers. Treat a live model request—not the authorization screen—as the readiness gate.

Login checklist

  • Confirm the account has an active SuperGrok or X Premium+ subscription.
  • Run hermes model and select xAI Grok OAuth (SuperGrok / X Premium+).
  • Open the verification URL, enter the displayed code if requested, and approve access.
  • Select a currently listed Grok model rather than relying on an old default name.
  • Run hermes doctor to inspect the saved authentication state.
  • Start a fresh session and make one small inference request.
  • If xAI returns 403 after login, evaluate the API-key provider instead of looping through OAuth.
  • Enable optional xAI media or search toolsets only when the workflow needs them.
hermes model
hermes auth add xai-oauth
hermes doctor

Remote and headless login

The xAI path uses device code, so a remote server does not need a loopback callback or SSH port forward. Run:

hermes auth add xai-oauth --no-browser

Open the printed URL on another device and leave Hermes running while it polls for approval. The code expires, so restart the flow if authorization times out.

Tokens and optional xAI tools

Hermes stores OAuth credentials in its authentication store and refreshes them before expiry. If refresh is revoked or fails with a terminal OAuth error, re-run hermes auth add xai-oauth; repeated retries with the same dead refresh token are not a fix.

The official guide says the same OAuth bearer token can be reused by supported direct-to-xAI surfaces such as text-to-speech, image, video, transcription, and X search. Tool availability, account entitlement, and enablement are separate checks. For example, video generation must be enabled before the agent can call its tool.

Common pitfalls

  • Assuming an active in-app subscription guarantees OAuth API access.
  • Treating HTTP 403 after successful login as an expired-token problem.
  • Setting XAI_API_KEY and expecting the xai-oauth provider to use it.
  • Waiting for a local browser on a headless server instead of using --no-browser.
  • Publishing the verification code, token store, or account details in logs or screenshots.
  • Assuming optional xAI tools are enabled because chat authentication succeeded.

Verification steps

  1. Run hermes doctor and confirm xai-oauth is logged in.
  2. Inspect the active provider and model without exposing token data.
  3. Send a harmless prompt and confirm inference succeeds without 401 or 403.
  4. If using an optional xAI tool, enable only that toolset and test it separately.
  5. If OAuth inference remains entitlement-blocked, configure the documented xai API-key path through the supported secret flow and re-test.

Official documentation

https://hermes-agent.nousresearch.com/docs/guides/xai-grok-oauth

Related pages