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):

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

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"