Xai Grok Onboarding
Connect an existing xAI subscription (X Premium through SuperGrok Heavy) to your agent runtime via RFC 8628 device-code OAuth so Grok models work without a separate API key.
Overview
xAI Grok Onboarding is an agent skill for the Build phase that connects xAI accounts to agents through OAuth 2.0 device-code login and tier-aware Grok model access.
Install
npx skills add https://github.com/starchild-ai-agent/official-skills --skill xai-grok-onboardingWhat is this skill?
- OAuth 2.0 device authorization grant (RFC 8628)—script-mode skill with bash-callable exports, no registered tools
- Tier mapping from JWT (1–4) to approximate grok-4.3, grok-4.20, reasoning, grok-build-0.1, and multi-agent access
- Supports X Premium, X Premium+, SuperGrok, and SuperGrok Heavy accounts via auth.x.ai
- status() reports user tier for model availability expectations
- Protected skill flag—read SKILL then invoke exports from a bash block
- Uses OAuth 2.0 RFC 8628 Device Authorization Grant.
- Documents a 4-tier JWT tier mapping (1 X Premium through 4 SuperGrok Heavy) for approximate model access.
- Skill version 1.3.0 in frontmatter.
Adoption & trust: 1.1k installs on skills.sh; 13 GitHub stars.
What problem does it solve?
You pay for X Premium or SuperGrok but your agent stack still expects a manual xAI API key or cannot see which Grok models your subscription unlocks.
Who is it for?
Solo builders standardizing on subscription-backed Grok inside script-mode or multi-agent Starchild workflows.
Skip if: Teams that require enterprise API-key governance only, or users who will not run bash onboarding scripts in their agent environment.
When should I use this skill?
User wants to sign in with xAI account, SuperGrok, X Premium, log in with Grok, or connect subscription-backed Grok models.
What do I get? / Deliverables
After device-code OAuth completes, your runtime can call tier-appropriate Grok models and status() clarifies which model families your subscription tier exposes.
- Authenticated xAI session usable for Grok model calls
- Tier status output guiding which model families are available
Recommended Skills
Journey fit
Build agent-tooling is where solo builders wire model providers into Claude Code–style stacks; onboarding auth belongs on that shelf. Agent-tooling covers provider login, model access tiers, and script-export setup rather than product feature code.
How it compares
Subscription OAuth onboarding skill—not the same as BYOK vendor API key setup documented in byok-custom-model.
Common Questions / FAQ
Who is xai-grok-onboarding for?
Builders using Starchild-style official skills who want Grok models via their xAI/X subscription instead of provisioning a standalone API key.
When should I use xai-grok-onboarding?
During build agent-tooling setup when you say use my SuperGrok, log in with Grok, connect X Premium, or need grok-4.x models after OAuth device login.
Is xai-grok-onboarding safe to install?
It handles OAuth tokens and is marked protected—review the Security Audits panel on this Prism page and only run onboarding in environments you trust.
Workflow Chain
Then invoke: byok custom model
SKILL.md
READMESKILL.md - 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 --- ## 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](https://github.com/NousResearch/hermes-agent/issues/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 ```bash 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") ```bash python