Skill v1.3.2
currentAutomated scan100/100+1 new
name: xai-grok-onboarding version: 1.3.2 description: | Connect an xAI account (X Premium / X Premium+ / SuperGrok / SuperGrok Heavy) via OAuth 2.0 device-code login.
Use when the user wants to sign in with their xAI account (e.g. "use my SuperGrok", "log in with Grok", "connect my X Premium"). author: starchild delivery: script protected: true tags: [xai, grok, oauth, supergrok, x-premium, login, subscription, multi-agent]
🟢 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-modelskill — for vendor-key BYOK setup (xAI API key from console.x.ai, different mechanism — bills per-token, NOT subscription-backed)chatgpt-codex-onboardingskill — same pattern, for ChatGPT/Codex subscriptionconfig/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_deniedfrom the token endpoint - Hermes Agent has documented the same in issue #26847
If poll() returns AccountAccessDenied:
- Verify the user's SuperGrok subscription is active (grok.com / settings)
- Suggest they try the verification URL in their already-logged-in browser (not a fresh incognito)
- If still denied → fall back to BYOK API key path (
byok-custom-modelskill, 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, syssys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')from exports import startprint(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, syssys.path.insert(0, '/data/workspace/skills/xai-grok-onboarding')from exports import pollprint(json.dumps(poll(), indent=2))EOF
Three terminal outcomes:
status="connected"→ success; show the userdefault_model_idto switch tostatus="pending"→ user hasn't approved yet; ask them to confirm before re-pollingok=falsewithaccess_denied→ see "account gate" section aboveok=falsewithexpired→ device code timed out (15 min); callstart()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 newxai-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 variantxai-grok/grok-4.20-0309-non-reasoning— faster, no reasoningxai-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:
- Go to https://grok.com → Settings → Account → "Connect your X Account" (links the two identities so xAI can verify subscription status)
- Make sure the linked X account is the one carrying the Premium / Premium+ tag
- Sign out + sign back in at https://accounts.x.ai once after linking (refreshes the entitlement)
- 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_KEYpath 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-modelskill 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
429or "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:
- Get a key at https://console.x.ai (pay-per-token, separate from subscription)
- Use
byok-custom-modelskill with the xAI template - 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:
refresh()— try the manual refresh path- If still failing,
logout()+ restart fromstart()
Critical rules
- Never paste user_code into the verification URL field for the user. The URL
accounts.x.ai/oauth2/device?user_code=XXXXalready 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.