[Feat] Add xAI Grok subscription OAuth

.gitleaks.toml

@@ -0,0 +1,18 @@
+# Roomote gitleaks configuration.
+# Extends default rules; only add allowlist entries with a concrete reason.
+#
+# Scope allowlists to the specific value, never to a whole file: a path
+# allowlist exempts every future line in that file from every rule.
+
+title = "Roomote"
+
+[allowlist]
+description = "False positives and intentional public identifiers"
+
+# Public Grok CLI OAuth client id reused by peer tools for SuperGrok
+# device-code login. This is not a secret; it is the same client_id published
+# by ecosystem agents (Hermes, OpenClaw, CC Switch) for auth.x.ai. It is
+# UUID-shaped, which is the only reason the default rules flag it.
+regexes = [
+  '''b1a00492-073a-47ea-816f-4c329264a828''',
+]

apps/api/src/handlers/inference/registry.ts

@@ -6,6 +6,7 @@ import {
 } from '@roomote/types';
 import {
   getFreshChatGptAccessToken,
+  getFreshXaiAccessToken,
   getGitHubCopilotAccessToken,
   resolveModelProviderEnvValue,
 } from '@roomote/db/server';
@@ -32,6 +33,8 @@ export type GatewayUpstreamResolution =
  * - `api-key`: inject the deployment's static key at the request path.
  * - `chatgpt-oauth`: mint a fresh subscription access token, add the
  *   account-id header, and collapse the request onto the Codex backend.
+ * - `xai-oauth`: prefer a connected Grok subscription access token, then
+ *   fall back to `XAI_API_KEY`.
  */
 export async function resolveGatewayUpstream(
   provider: InferenceGatewayProvider,
@@ -46,6 +49,10 @@ export async function resolveGatewayUpstream(
     return resolveGitHubCopilotUpstream(provider, upstreamPath, search);
   }
 
+  if (provider.authStrategy === 'xai-oauth') {
+    return resolveXaiUpstream(provider, upstreamPath, search);
+  }
+
   const [apiKey, upstreamBaseUrl] = await Promise.all([
     resolveModelProviderEnvValue(provider.envVarNames),
     resolveProviderUpstreamBaseUrl(provider),
@@ -76,6 +83,49 @@ export async function resolveGatewayUpstream(
   };
 }
 
+/**
+ * xAI supports both SuperGrok OAuth and a BYOK API key. Prefer a connected
+ * subscription (fresh access token) so subscription users never need a key;
+ * fall back to the deployment key when only that is configured.
+ */
+async function resolveXaiUpstream(
+  provider: InferenceGatewayProvider,
+  upstreamPath: string,
+  search: string,
+): Promise<GatewayUpstreamResolution> {
+  const [oauthToken, apiKey, upstreamBaseUrl] = await Promise.all([
+    getFreshXaiAccessToken(),
+    resolveModelProviderEnvValue(provider.envVarNames),
+    resolveProviderUpstreamBaseUrl(provider),
+  ]);
+
+  const bearer = oauthToken?.access ?? apiKey;
+
+  if (!bearer) {
+    return {
+      ok: false,
+      status: 404,
+      error:
+        'No connected xAI Grok subscription or XAI_API_KEY is available for this deployment',
+    };
+  }
+
+  return {
+    ok: true,
+    resolved: {
+      upstreamUrl: `${upstreamBaseUrl}${upstreamPath}${search}`,
+      headers: provider.authHeader
+        ? {
+            [provider.authHeader.name]: formatProviderAuthHeaderValue(
+              provider,
+              bearer,
+            ),
+          }
+        : {},
+    },
+  };
+}
+
 async function resolveGitHubCopilotUpstream(
   provider: InferenceGatewayProvider,
   upstreamPath: string,

apps/docs/environment-variables.mdx

@@ -180,7 +180,8 @@ as per-task auth tokens or workspace paths.
 | `AI_GATEWAY_API_KEY`                   | Provider key | Vercel AI Gateway API key.                                                                                                              |
 | `OPENAI_API_KEY`                       | Provider key | OpenAI API key.                                                                                                                         |
 | `ANTHROPIC_API_KEY`                    | Provider key | Anthropic API key.                                                                                                                      |
-| `XAI_API_KEY`                          | Provider key | xAI / Grok API key.                                                                                                                     |
+| `XAI_API_KEY`                          | Provider key | xAI / Grok API key. Optional when a SuperGrok / eligible X Premium+ subscription is connected from **Settings > Models**.               |
+| `XAI_OAUTH_CLIENT_ID`                  | Optional     | Override for the public Grok CLI OAuth client id used by the SuperGrok device-code connect flow. Defaults to the public CLI client id.  |
 | `MOONSHOT_API_KEY`                     | Provider key | Moonshot AI / Kimi Open Platform API key.                                                                                               |
 | `KIMI_API_KEY`                         | Provider key | Kimi for Coding API key for `kimi-for-coding/...` models.                                                                               |
 | `MINIMAX_API_KEY`                      | Provider key | MiniMax API key.                                                                                                                        |

apps/docs/models.mdx

@@ -17,9 +17,9 @@ Configure models from **Settings > Models**.
 An inference provider is the service that hosts or routes model calls. Roomote
 supports providers such as OpenRouter, Vercel AI Gateway, Baseten,
 Together AI, OpenAI, Anthropic, Moonshot AI, Kimi for Coding, MiniMax, Z.AI,
-Z.AI Coding Plan, OpenCode, Amazon Bedrock, Google Gemini, xAI, GitHub Copilot,
-ChatGPT subscriptions, and OpenAI-compatible endpoints such as LiteLLM, Ollama,
-and vLLM.
+Z.AI Coding Plan, OpenCode, Amazon Bedrock, Google Gemini, xAI (API key or
+Grok subscription), GitHub Copilot, ChatGPT subscriptions, and
+OpenAI-compatible endpoints such as LiteLLM, Ollama, and vLLM.
 
 You can connect more than one inference provider in the same deployment. That
 lets you mix and match models by provider instead of betting the whole
@@ -138,12 +138,16 @@ list.
 - **Models** controls the provider/model pairs that are available, the default
   model, and specialized model roles.
 
-For subscription-based providers (ChatGPT, GitHub Copilot, and Kimi for
-Coding), the provider row also shows current plan usage when the provider
-reports it, such as remaining Copilot premium requests or the percent used of
-the ChatGPT 5-hour and weekly limits. These numbers come from unofficial
-provider endpoints, so the usage line is hidden whenever the provider does not
-return usable data.
+For subscription-based providers (ChatGPT, GitHub Copilot, Kimi for Coding, and
+xAI Grok / SuperGrok), the provider row also shows current plan usage when the
+provider reports it, such as remaining Copilot premium requests, the percent
+used of the ChatGPT 5-hour and weekly limits, or Grok included-usage windows.
+These numbers come from unofficial provider endpoints, so the usage line is
+hidden whenever the provider does not return usable data.
+
+xAI can be connected with an API key, a SuperGrok or eligible X Premium+
+subscription, or both. When both are configured, the subscription is preferred
+at runtime for `xai/` models.
 
 Admins can enable or disable models from the task model list. The default model
 must stay enabled, because Roomote uses it when a task does not request a