xai-grok-onboarding

🟢 xAI OAuth Onboarding

Use any active xAI account — X Premium, X Premium+, SuperGrok, or SuperGrok Heavy — for grok-4.3, grok-build-0.1, grok-4.20-* and multi-agent models. No separate API key needed.

This is standard OAuth 2.0 (RFC 8628 Device Authorization Grant), not a vendor-custom flow.

Tier → model access

The JWT issued by auth.x.ai carries a tier claim; higher tiers unlock more models from /v1/models. Observed mapping (xAI does not publish this officially):

Tier	Subscription	Approx. model access
1	X Premium ($8/mo)	grok-4.3 baseline
2	X Premium+ ($16/mo)	+ grok-4.20-0309 variants
3	SuperGrok ($30/mo)	+ reasoning models
4	SuperGrok Heavy ($300/mo)	+ grok-build-0.1 + multi-agent

status() reports the user's tier so they know which models will be available.

This is a script-mode skill — no tools registered. Read this file, then call the exports from a bash block.

See also

• byok-custom-model skill — for vendor-key BYOK setup (xAI API key from console.x.ai, different mechanism — bills per-token, NOT subscription-backed)
• chatgpt-codex-onboarding skill — same pattern, for ChatGPT/Codex subscription
• config/context/references/model-onboarding.md — overall model-selection landscape

Backend compatibility

This skill depends on the core.xai_grok Python package inside the platform image (shipped 2026-05-22). On older images the skill loads cleanly but every public function returns:

{
  "ok": false,
  "error": "xai_oauth_backend_unavailable",
  "detail": "ModuleNotFoundError: core.xai_grok not found in any of: [/app, /data/workspace/starchild-clawd]",
  "hint": "Update the platform image OR fall back to byok-custom-model with an xAI API key."
}

If you see this response, do NOT retry — the platform itself needs an update. Either wait for the image refresh or guide the user to byok-custom-model with an API key from console.x.ai.

---

When to use this skill

✅ Use when the user EXPLICITLY says one of:

• "Sign in with my Grok / SuperGrok account"
• "Use my SuperGrok / X Premium subscription"
• "Connect SuperGrok Heavy"
• "Login with xAI / Grok"
• "Use my Grok Heavy subscription"

❌ Do NOT use for:

• "Add Grok via API key" / "I have an xAI API key" → use byok-custom-model (the xAI template)
• Other vendors (Anthropic, OpenAI, Gemini, Qwen, etc.) → use byok-custom-model
• "Add the Grok model" without subscription mention → ASK the user which path they want (subscription OAuth vs. API key BYOK)

The two paths are mutually exclusive billing-wise. Subscription OAuth uses the user's monthly quota; BYOK API key uses console.x.ai pay-per-token credits.

---

Critical preflight — account gate awareness

xAI has a known backend gate that denies OAuth grants for some accounts even with an active SuperGrok subscription. This is upstream xAI behavior, not a client bug. Symptoms:

• Verification page loads, but clicking "Approve" returns access_denied from the token endpoint
• Hermes Agent has documented the same in issue #26847

If poll() returns AccountAccessDenied:

1. Verify the user's SuperGrok subscription is active (grok.com / settings)
2. Suggest they try the verification URL in their already-logged-in browser (not a fresh incognito)
3. If still denied → fall back to BYOK API key path (byok-custom-model skill, xAI template, key from https://console.x.ai)

Do NOT silently retry — the gate is deterministic per account, retrying wastes time.

---

Flow

The flow has 4 user-visible steps. Drive it like this:

1. start() — generate the verification URL

python3 - <<'EOF'
import json, sys
sys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')
from exports import start
print(json.dumps(start(), indent=2))
EOF

Returns verification_url_with_code — tell the user to open it in their browser, log in (if needed), and click Approve.

⚠️ Wait for explicit user confirmation before calling poll(). Polling too eagerly burns tokens for a "still pending" state.

2. poll() — confirm approval (after the user says "done")

python3 - <<'EOF'
import json, sys
sys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')
from exports import poll
print(json.dumps(poll(), indent=2))
EOF

Three terminal outcomes:

• status="connected" → success; show the user default_model_id to switch to
• status="pending" → user hasn't approved yet; ask them to confirm before re-polling
• ok=false with access_denied → see "account gate" section above
• ok=false with expired → device code timed out (15 min); call start() again

3. After successful connect — tell the user

When poll() returns status='connected', the first thing you must do is tell the user:

"Connection successful. Please refresh your browser page — once it reloads, the new xai-grok/* models will appear in the model picker."

The web frontend caches the model list client-side and does not auto-refresh after an OAuth connect completes. Without a manual page refresh the user will not see their newly available models and will think the connection failed. Always include this instruction in your reply — do not assume the picker updates on its own.

After the refresh, the default model is xai-grok/grok-4.3. Other available models depend on the subscription tier (SuperGrok Heavy unlocks grok-build-0.1).

To switch: /model xai-grok/grok-4.3 or use the picker.

---

Function reference

Function	Args	Returns
status()	—	Current credential state + available models + expiry
start()	—	Device code prompt: {verification_url_with_code, user_code, expires_in_seconds}
poll(pending_id=None)	optional pending_id	{status: connected/pending} + credential info
logout()	—	Delete credential + flush agent cache
refresh()	—	Force-refresh access token (debug; normally automatic)
models(force=False)	—	List available models from the OAuth endpoint

force=True on models bypasses the cache TTL.

All functions return a dict with ok: True on success or ok: False, error: "..." on failure.

---

After connecting

Models surface with the xai-grok/ prefix:

• xai-grok/grok-4.3 — primary chat model (default)
• xai-grok/grok-build-0.1 — Grok Build coding model (SuperGrok Heavy tier only)
• xai-grok/grok-4.20-0309-reasoning — reasoning variant
• xai-grok/grok-4.20-0309-non-reasoning — faster, no reasoning
• xai-grok/grok-4.20-multi-agent-0309 — multi-agent variant (uses /v1/responses internally)

User switches via /model xai-grok/grok-4.3 or the model picker UI.

Lane routing (transparent)

The provider auto-routes based on model id:

• Multi-agent models → https://api.x.ai/v1/responses (Responses API)
• All other Grok models → https://api.x.ai/v1/chat/completions (OpenAI-compatible)

Users do not need to know which dialect each model speaks — passing the standard messages=[...] shape works for both. For multi-agent, an optional thinking={"effort": "low"|"medium"|"high"} controls how many agents collaborate.

Subsequent chat calls hit https://api.x.ai/v1 directly using the OAuth bearer — bypasses the platform proxy. Subscription usage limits apply (not the platform credit balance). Image / video models (grok-imagine-*) are filtered out of the chat picker but accessible via image generation tools.

---

xAI's OAuth allowlist — biggest cause of "frontend rejected my login"

Critical context (verified from independent implementations, 2026-05): xAI's backend maintains an internal allowlist on the OAuth API surface and frequently returns HTTP 403 to OAuth tokens even when the user's subscription is active and the device-code flow itself succeeded. This is documented by Hermes Agent (their xAI OAuth troubleshooting) and confirmed by independent OpenCode plugin authors. It is not a bug in our adapter — switching to PKCE flow does not bypass it (both grant types hit the same allowlist).

Subscription tier ↔ OAuth availability (observed, not guaranteed)

Subscription	Price	OAuth typical outcome
X Premium (X.com only)	$8 /mo	❌ Often rejected — not enough entitlement
X Premium+ (linked X account)	$16 /mo	✅ Usually works — xAI auto-links via X account
SuperGrok (grok.com direct)	$30 /mo	⚠️ Mixed — some users blocked, some pass
SuperGrok Heavy	$300 /mo	✅ Reliably works

Preflight before starting the flow

If the user has a standalone X Premium subscription (not Premium+) or a SuperGrok base subscription and is hitting frontend rejection, tell them to do this first, in order:

1. Go to https://grok.com → Settings → Account → "Connect your X Account" (links the two identities so xAI can verify subscription status)
2. Make sure the linked X account is the one carrying the Premium / Premium+ tag
3. Sign out + sign back in at https://accounts.x.ai once after linking (refreshes the entitlement)
4. Retry the device-code flow

A large share of reported "OAuth login fails / device code never accepted" cases trace back to missing X account link — xAI's backend can't verify the Premium status without the link, and the front door silently rejects the device code.

When OAuth still fails after preflight → recommend BYOK

The standard fix in the community (Hermes, OpenCode plugin, etc.) is stop fighting OAuth, switch to API key:

• The XAI_API_KEY path uses a different xAI backend (console.x.ai pay-per-token) that is not subject to the OAuth allowlist.
• Tell the user to grab a key at https://console.x.ai and then route them to the byok-custom-model skill with the xAI template. Setup is two minutes.
• Trade-off: BYOK bills per-token from a separate wallet instead of using the subscription quota — explain that clearly so the user picks consciously.

What we do NOT do

• ❌ Spoof referrer / pretend to be another known client (Hermes, grok-cli, etc.) — bypassing entitlement is against ToS and xAI may tighten the allowlist further
• ❌ Retry the device-code flow on access_denied — it will keep failing; recommend preflight or BYOK instead
• ❌ Tell the user it's a Starchild bug — it's an xAI account-gating decision we cannot override

---

Limits & BYOK fallback

xAI does not publish exact daily caps or RPM the way OpenAI does. Practical reality for OAuth-backed Grok usage:

• No published hard numbers. Limits are fair-use based — xAI throttles temporarily if you generate massive volume in a short window.
• Tier matters. Heavy ($300/mo) gives the highest consumer ceiling — significantly above SuperGrok ($30) or X Premium+. Standard text/chat rarely hits the cap for normal-to-heavy daily use.
• Image / video / voice have tighter quotas. E.g. Heavy users get roughly ~80+ video generations per 12 hours, but these can still throttle during peak load.
• Soft ceiling signal: if the user starts seeing 429 or "rate limit exceeded" messages from xAI, they've hit the fair-use ceiling for that feature. Wait it out (limits reset on a rolling window, not a fixed daily clock) or switch billing modes.

When to suggest switching to BYOK

If the user wants predictable, spend-based high-volume access — or if they're hitting limits often — they can switch to a regular xAI API key:

1. Get a key at https://console.x.ai (pay-per-token, separate from subscription)
2. Use byok-custom-model skill with the xAI template
3. BYOK models appear alongside OAuth models in the picker — switch per turn

Both paths can coexist; the user picks per request. OAuth = subscription quota (good default). BYOK = clearer rate limits + per-token billing (good for heavy automation or when you want cost transparency).

Error → action table

Symptom	Cause	Action
429 / "rate limit exceeded" on chat	OAuth fair-use ceiling hit	Wait for soft reset, or switch this request to BYOK
403 / access_denied at OAuth time	xAI account gated	Use BYOK (see preflight section above)
Repeated 401 after refresh()	Token revoked / subscription canceled	logout() + restart, or switch to BYOK
503 / 5xx upstream	xAI infra issue	Retry shortly. BYOK uses the same upstream, won't help

---

Reauth

Tokens auto-refresh via refresh_token (6h access token TTL — relatively generous vs Codex's 1h). If a 401 surfaces:

1. refresh() — try the manual refresh path
2. If still failing, logout() + restart from start()

---

Critical rules

• Never paste user_code into the verification URL field for the user. The URL accounts.x.ai/oauth2/device?user_code=XXXX already embeds the code — just open it.
• Never start the flow without explicit user request. "I want to use Grok" needs a follow-up question about subscription vs. API key; "use my SuperGrok subscription" is enough.
• Wait for user confirmation between start and poll. Auto-polling wastes API calls and produces stale "pending" responses.
• On access_denied, do NOT retry blindly. Explain the gate, suggest BYOK fallback.
• Never log or echo the access_token / refresh_token. They're persistent credentials. The exports never include them in return values either.