xAI SuperGrok Device Login

Sign in with a SuperGrok subscription instead of an API key and run an agent through xAIResponses.

Sign in with a SuperGrok subscription instead of an API key and run an agent through xAIResponses. The device flow prints a URL and a code; approve the sign-in in the browser and the token manager can store and refresh the token. Encrypted reuse across restarts requires the storage setup below.

Use an xAI account with API access for the selected model. Browser sign-in alone does not establish subscription eligibility or available quota.

oauth_device_login.py
"""
Xai SuperGrok Device Login
==========================

Sign in with a SuperGrok subscription instead of an API key and run an agent
through xAIResponses. The device flow prints a URL and a code; approve the
sign-in in the browser and the token is stored encrypted and refreshed
automatically across restarts.

Requires XAI_TOKEN_ENCRYPTION_KEY. Generate a key with:
python -c "from agno.utils.encryption import generate_encryption_key; print(generate_encryption_key())"
"""

import time

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.xai import xAIResponses
from agno.models.xai.oauth import XAITokenManager

# SqliteDb is for local development only; use PostgresDb in production
db = SqliteDb(db_file="tmp/xai_oauth.db")
token_manager = XAITokenManager(db=db)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    # --- Sign in with the device flow ---
    info = token_manager.start_device_login()
    print("Open this URL and approve the sign-in:")
    print(info.verification_uri_complete)
    print("Code: " + info.user_code)
    token_manager.poll_for_token(
        info.device_code, info.interval, time.time() + info.expires_in
    )
    print("Signed in. The token is stored encrypted and refreshes automatically.")

    # --- Model class syntax ---
    agent = Agent(model=xAIResponses(token_manager=token_manager), markdown=True)
    agent.print_response("Share a 2 sentence horror story")

    # --- String syntax ---
    agent = Agent(model="xai-responses:grok-4.3", markdown=True)
    # Attach the SuperGrok session to the model the string resolved to
    agent.model.token_manager = token_manager
    agent.print_response("Share a 2 sentence horror story")

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno openai sqlalchemy cryptography

Configure encrypted token storage

Generate an encryption key once in the activated environment:

python -c "from agno.utils.encryption import generate_encryption_key; print(generate_encryption_key())"

Copy the generated key into the environment variable below. Keep the same key in your secret storage and restore it on later runs; do not generate a new one on every restart.

export XAI_TOKEN_ENCRYPTION_KEY="paste_the_generated_key_here"
unset XAI_API_KEY

A missing encryption key keeps new tokens in process memory; a placeholder or invalid key cannot encrypt them. Encrypted reuse needs a successful database write, the same key and the same database on later runs. Token refresh also requires a valid grant and provider access. Clearing XAI_API_KEY makes this example exercise OAuth without falling back to a separate API key.

Run the example

Save the code above as oauth_device_login.py, then run:

python oauth_device_login.py

Full source: cookbook/90_models/xai/oauth_device_login.py