ExtensionProvider@piex-dev/xai-oauth

xai-oauth — Subscription Login for Grok, Not API-Key-Locked

TL;DR

If you already pay for a Grok subscription, @piex-dev/xai-oauth lets Pi use that quota; the API Key path stays for automation and metered use.

Overview

Pi's built-in xai uses an API Key (metered, fixed model set, good for CI). But many users hold a SuperGrok subscription or X Premium+ quota — already paid, yet forced to open another API Key on a separate ledger. @piex-dev/xai-oauth adds xAI Grok to /login, authorizes via standard device-code OAuth, discovers models in the background after login (subscription vs public API routed separately), and coexists with the built-in xai.

How it works

Device Authorization Grant (RFC 8628): the extension acts as a public client (no secret), requests a device_code, the user authenticates on the official page, and the extension only gets a token; refresh_token renews before access_token expiry. After login it pulls /v1/models from both endpoints (public API api.x.ai + subscription proxy cli-chat-proxy.grok.com) and merges into the provider table — new models appear after /reload, no npm upgrade needed.

built-in xai	xai-oauth
API Key auth	OAuth subscription
metered billing	subscription quota
fixed public set	fallback + live discovery
built-in	extension

Usage

Install

bash

pi install npm:@piex-dev/xai-oauth

Source: extensions/xai-oauth

Usage

flow

/login → pick xAI Grok (SuperGrok / X Premium+)
→ browser opens the verification page
→ /model grok-4.5 (or whatever id appears)

Configuration

Model whitelist/order: PI_XAI_OAUTH_MODELS=grok-build,grok-4.5. Subscription token stored in Pi's standard storage, never on disk in the extension. /reload picks up new models.

Verify

bash

bun test extensions/xai-oauth/test/xai-oauth.test.ts extensions/xai-oauth/test/models.test.ts

Implementation

xai-oauth.ts OAuth flow + registerProvider; models.ts catalog/discovery/merge/routing. One of the few piex packages with unit tests. Security posture: error truncation (extract only error/error_description, length-capped, no full response in logs); endpoint validation (*.x.ai only); token skew (expire minutes early + minimum TTL floor); slow_down (increase polling interval). Model layer: fallback catalog (offline-usable) + triggerDiscovery (background fetch after login) + rebuildModelsForOAuth (merge, mark routing) + env var filter.

Design notes

Project	Mechanism	piex choice
oh-my-pi xai-oauth	full RFC 8628 flow; dual-endpoint discovery; standard OAuth provider registration	Adopted: flow chain, client_id (same source), endpoint validation, error truncation/skew. Not adopted: Bun runtime
stnly/pi-grok	pull /v1/models and merge into provider	Borrowed: live-discovery idea, implementation rewritten independently
pi built-in xai	API Key + fixed model set	Coexist: Key/CI + subscription/interactive, no conflict

Core trade-off: subscription token in Pi's standard storage (extension never persists), best-effort model discovery (fall back to fallback on failure), security posture "under-report rather than mis-report".

Changelog

Roadmap

Direction	Plan
Strong xAI-side dependency	thin wrapper + fast follow; OIDC/device-code contract tests (snapshot mock) against regressions
Best-effort discovery	/models or status marks source (discovered/fallback) and routing; PI_XAI_OAUTH_MODELS as first-class config
Raw error/quota semantics	per-error-class next steps (re-/login, switch model, check subscription)
Confusable with built-in xai	UI/status clarifies current provider and billing path
Enterprise uncovered	stabilize personal subscription path; evaluate enterprise separately

Version history

Version	Date	Changes
0.1.1	2026-07-19	Initial release: RFC 8628 OAuth flow; dual-endpoint model discovery (public API + subscription proxy); fallback catalog + triggerDiscovery + rebuildModelsForOAuth routing merge; PI_XAI_OAUTH_MODELS whitelist; security posture (error truncation, endpoint validation *.x.ai, token skew, slow_down); subscription token via Pi standard storage, no disk; unit-test coverage

Source Markdown: docs/packages/xai-oauth.md