grok-build-auth

What it is

Protocol research client for x.ai / Grok Build OAuth workflow. It reproduces the registration → SSO → OAuth PKCE → local auth JSON export chain using pure HTTP (curl_cffi fingerprint) without relying on a browser.

How it works

• Modules: run.py orchestrates registration (client.py via email + Turnstile), SSO extraction from cookies, OAuth PKCE with consent, and export to local auth JSON compatible with CLIProxyAPI.
• Export format: local JSON with fields including type, auth_kind, access_token, refresh_token, base_url, and headers for CPA loading.
• Architecture diagram shows flow: run.py → client.py → sso.py → oauth_protocol.py → token exchange → cliproxyapi_auth/*.json.

Getting started

Installation

git clone https://github.com/<you>/grok-build-auth.git
cd grok-build-auth
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env
# Edit .env with your keys, do not commit

Configuration

| Variable | Required | Description | |---|---|---| | YESCAPTCHA_API_KEY | Yes | Turnstile captcha key | | TEMPMAIL_API_KEY | -e tempmail 时 | Temporary email API key | | CLOUDFLARE_API_TOKEN | -e cloudflare 时 | CF API token | | CLOUDFLARE_ACCOUNT_ID | 同上 | CF account | | CLOUDFLARE_D1_DB_ID | 同上 | CF D1 DB ID | | ALIAS_MAIL_DOMAINS | 同上 | Allowed email domains | | CLIPROXYAPI_AUTH_DIR | 否 | Default ./cliproxyapi_auth | | HTTPS_PROXY / HTTP_PROXY | 否 | Proxy settings |

Running (research / own account)

# complete chain once
python run.py -n 1

# concurrent registrations; OAuth remains serial
python run.py -n 5 -t 3

# self-hosted Cloudflare email backend
python run.py -n 1 -e cloudflare

# only register + SSO (no CPA export)
python run.py -n 1 --no-oauth

# specify CLIProxyAPI auth dir
python run.py -n 1 --cliproxyapi-auth-dir /path/to/CLIProxyAPI/data/auth

# OAuth debug logs
python run.py -n 1 --oauth-debug

Auxiliary scripts

# with existing account: run OAuth only
python xai_oauth_login.py

# export OAuth output to CPA auth format
python xai_oauth_export_cliproxyapi.py --cliproxyapi-auth-dir ./cliproxyapi_auth

# probe build quota (mask tokens)
python xai_build_quota_probe.py --auth-dir ./cliproxyapi_auth

Export file shape (local, not official keys)

{
  "type": "xai",
  "auth_kind": "oauth",
  "access_token": "...",
  "refresh_token": "...",
  "base_url": "https://cli-chat-proxy.grok.com/v1",
  "headers": {
    "X-XAI-Token-Auth": "xai-grok-cli",
    "x-grok-client-version": "0.2.93",
    "x-grok-client-identifier": "grok-shell"
  }
}

Known limitations

• Dependent on external services; may break if upstream changes.
• Turnstile / email service stability affects success rate and duration.
• High concurrency may trigger platform risk controls; use for research with restraint.
• SSO alone does not equal CPA auth; OAuth must be completed.
• Playwright is optional; default path does not require it.