Configure an external auth provider for Grok Build

Point Grok Build at an executable that mints tokens for a corporate IdP or custom token broker. Official: Enterprise Deployments.

Wire the command

In ~/.grok/config.toml (or a managed layer):

[auth]
auth_provider_command = "/usr/local/bin/your-auth-provider"

The command must print either a bare token string or JSON:

{"access_token": "...", "refresh_token": "...", "expires_in": 3600}

refresh_token and expires_in are optional.

Two contracts: refresh vs sign-in

Grok sets GROK_AUTH_EXPIRED so the provider knows which case it is in:

GROK_AUTH_EXPIRED	Meaning	What the command should do
1	Background refresh over a credential Grok already holds	Mint silently or exit non-zero. Do not wait for input. Grok kills a slow refresh after a few seconds.
unset	Interactive sign-in (user attached)	May show stderr to the user; up to ~300 seconds for a browser or device-code round trip.

A provider that exits promptly on GROK_AUTH_EXPIRED=1 keeps the handover to the sign-in screen fast.

How it ranks with other auth

Grok Build supports browser OIDC (grok login), device code (grok login --device-auth), this external provider, and API key (XAI_API_KEY / model.api_key). When several credentials exist, resolution is per model: model.api_key > model.env_key > active session token > XAI_API_KEY.

To force enterprise SSO and block first-party API-key skip, pin in /etc/grok/requirements.toml:

[grok_com_config]
disable_api_key_auth = true
force_login_team_uuid = "<your-team-uuid>"

See the broader rollout guide: Deploy Grok Build for enterprise. Device-code login alone: Login to Grok Build with device code.

Pitfalls

• Prompting for input during a refresh (GROK_AUTH_EXPIRED=1) — Grok will kill the hang.
• Putting the provider only in a project .grok/config.toml — auth belongs in user or managed config.
• Leaving a personal XAI_API_KEY in the environment when fleet policy requires SSO.