02 authentication

Providers & Authentication

Bucket Agent is multiprovider by design. It works without any authentication (local Ollama), with an API key, or with enterprise SSO. This guide explains all available options.

Bucket supports several authentication methods, including interactive browser login, enterprise single sign-on (SSO), and headless CI/CD runners.

---

Local Provider (No Auth Required)

No account, no API key. Just configure a local model and go:

# ~/.bucket/config.toml
[models]
default = "ollama-coder"

[model.ollama-coder]
model    = "qwen2.5-coder:latest"
base_url = "http://localhost:11434/v1"
name     = "Qwen 2.5 Coder (Ollama)"

ollama serve
ollama pull qwen2.5-coder:latest
bucket

Bucket detects non-xAI endpoints automatically and skips the login screen entirely.

---

Browser Login (Default)

On first launch, Bucket opens your browser to authenticate with bucket.com:

bucket

Bucket stores credentials in ~/.bucket/auth.json and reuses them across sessions. Bucket refreshes access tokens automatically in the background. When a token can't be refreshed, Bucket prompts you to sign in again. Credentials without a server-provided expiry fall back to a 30-day lifetime.

Credential storage

Tokens in ~/.bucket/auth.json (and MCP OAuth tokens in ~/.bucket/mcp_credentials.json) are written with owner-only permissions (0600 on Unix). Anyone with filesystem access to those paths can use the credentials, so:

• Prefer full-disk encryption (FileVault, BitLocker, LUKS, or equivalent).
• Do not copy auth.json or mcp_credentials.json into shared directories, tickets, or chat.
• On multi-user hosts, keep $HOME / $BUCKET_HOME private to your account.

Re-authenticate

To switch accounts or resolve an authentication problem, run:

bucket login

Running bucket login starts the sign-in flow again, replacing your cached session. By default, it opens your browser and signs in through SpaceXAI OAuth at auth.x.ai. Pass a flag to select a different flow:

Flag	Description
--oauth	Sign in through SpaceXAI OAuth at auth.x.ai. This is the default, so the flag is optional.
--device-auth (alias --device-code)	Sign in with the device-code flow for headless or remote environments.

To sign out, run bucket logout. It takes no flags and clears your cached credentials.

---

API Key

For CI/CD, automation, or environments without browser access, use an API key from console.x.ai:

export BUCKET_API_KEY="bucket-..."
bucket

Bucket uses the API key as a fallback when no session token is active. If you have already signed in interactively, the stored session token takes precedence. To fall back to the API key, run bucket logout or delete ~/.bucket/auth.json.

---

OIDC (Customer SSO)

Authenticate developers through your own Identity Provider (IdP) -- such as Okta, Azure AD, or Auth0 -- instead of bucket.com.

1. Register a public client in your IdP

• Grant type: Authorization Code with PKCE (Proof Key for Code Exchange)
• Redirect URI: http://127.0.0.1/callback -- a loopback address. Bucket binds a random port at sign-in time, and most IdPs treat the loopback redirect as port-agnostic per RFC 8252.
• No client secret. PKCE replaces it.

2. Configure the CLI

Via config file:

# ~/.bucket/config.toml
[bucket_com_config.oidc]
issuer = "https://acme.okta.com"
client_id = "0oa1b2c3d4e5f6g7h8i9"

Or via environment variables:

export BUCKET_OIDC_ISSUER="https://acme.okta.com"
export BUCKET_OIDC_CLIENT_ID="0oa1b2c3d4e5f6g7h8i9"

You can also override the API endpoint to point at your own proxy:

export BUCKET_CLI_CHAT_PROXY_BASE_URL="https://bucket-proxy.acme.com/v1"

3. Run bucket

The CLI discovers endpoints via {issuer}/.well-known/openid-configuration, opens the IdP login page, and stores tokens in ~/.bucket/auth.json. Tokens auto-refresh silently via the stored refresh_token.

Optional fields

Field	Default	Notes
scopes	["openid", "profile", "email", "offline_access", "api:access"]	offline_access enables silent token refresh
audience	None	Required by some IdPs (e.g., Auth0)

---

External Auth Provider

When browser-based login isn't possible -- for example, on sandboxed VMs, CI runners, or air-gapped networks -- delegate authentication to an external binary or script.

How It Works

+--------------+     sh -c     +------------------------+
|     Bucket     |-------------->|  your auth binary      |
|              |               |                        |
|  reads       |<-- stdout ----|  prints token          |
|  auth.json   |               |                        |
|              |   (stderr)    |  prints status/URLs    |--> surfaced to user
+--------------+               +------------------------+

1. Bucket runs your command via sh -c "<command>"
2. Your binary runs whatever auth flow it needs (SSO, device code, certificate exchange)
3. stderr carries human-readable output, such as login URLs and status messages. Bucket reads stderr and surfaces it to the user; in the TUI, it turns the first https:// URL into a clickable sign-in link.
4. stdout is captured by Bucket and saved as the access token
5. Exit 0 = success; exit non-zero = Bucket falls back to interactive login

The stdout / stderr Contract

Stream	What to print	Who sees it
stdout	The token -- nothing else	Bucket (parsed and stored in auth.json)
stderr	Login URLs, status messages, errors	The user (Bucket reads stderr and shows the sign-in URL as a clickable link in the TUI)

Do not print anything to stdout except the token. No progress messages, no debug output. Bucket reads stdout, trims surrounding whitespace, and parses the result as a token.

stdout Token Format

Bare string -- just the raw token:

eyJhbGciOiJSUzI1NiIs...

JSON -- with optional refresh token, expiry, and issuer:

{"access_token": "eyJhbGciOi...", "refresh_token": "ref-tok", "expires_in": 3600, "issuer": "https://idp.example.com"}

Use JSON if your tokens expire and you want Bucket to automatically re-run the binary before expiry.

JSON fields:

Field	Required	Meaning
access_token	yes	Bearer token Bucket sends to the xAI API
refresh_token	no	Stored for reference. Bucket refreshes by re-running your binary, not with an OAuth refresh grant
expires_in	no	Token lifetime in seconds; enables proactive refresh before expiry
issuer	no	Identifies the token's issuer

Configuration

Via config file:

# ~/.bucket/config.toml
[auth]
auth_provider_command = "/usr/local/bin/my-auth-provider"
auth_provider_label = "Acme Corp"   # optional -- customizes the TUI login button
auth_token_ttl = 3600               # optional -- token lifetime in seconds

Or via environment variables:

export BUCKET_AUTH_PROVIDER_COMMAND="/usr/local/bin/my-auth-provider"
export BUCKET_AUTH_PROVIDER_LABEL="Acme Corp"
export BUCKET_AUTH_TOKEN_TTL=3600

Token Refresh

When Bucket needs to refresh an expired token, it re-runs your binary with BUCKET_AUTH_EXPIRED=1 set in the environment. Each run fully replaces the stored credential, so emit the same JSON fields (such as issuer) on every invocation, including refreshes. Your binary can use this to take a faster silent-refresh path:

#!/bin/sh
if [ "$BUCKET_AUTH_EXPIRED" = "1" ]; then
    echo "Refreshing token..." >&2
    TOKEN=$(my-company-auth --refresh --silent)
else
    echo "Authenticating via Acme Corp SSO..." >&2
    TOKEN=$(my-company-auth --login --interactive)
fi

if [ -z "$TOKEN" ]; then
    echo "Authentication failed" >&2
    exit 1
fi

echo "{\"access_token\": \"$TOKEN\", \"expires_in\": 3600}"

Environment Variables

Variable	Description
BUCKET_AUTH_PROVIDER_COMMAND	Path to your auth binary
BUCKET_AUTH_PROVIDER_LABEL	Display name on the TUI login screen (e.g., "Acme Corp")
BUCKET_AUTH_TOKEN_TTL	Token lifetime in seconds (for bare-string tokens without expires_in)
BUCKET_AUTH_EXPIRED	Set to 1 by Bucket when re-running the binary for token refresh
BUCKET_AUTH_EARLY_INVALIDATION_SECS	Seconds before expiry to proactively refresh (default: 300)

---

Device Code Flow

For headless environments (SSH sessions, Docker containers, remote VMs) where no browser is available locally:

bucket login --device-auth    # or: bucket login --device-code

This prints a URL and code to the terminal. Open the URL on any device, enter the code, and complete authentication. Bucket polls until the login is confirmed.

You can also implement the device-code flow through an External Auth Provider for full control.

---

Automatic Credential Refresh

Bucket automatically refreshes expired credentials:

• Before expiry: If your auth provider returned expires_in (JSON output) or you set auth_token_ttl, Bucket re-runs the auth binary ~5 minutes before expiry.
• On auth error: If the server returns 401 Unauthorized, Bucket refreshes the credentials and retries the request.
• OIDC: If a refresh_token is available, Bucket silently refreshes via your IdP without re-opening the browser.

Tune the refresh buffer:

# Refresh 5 minutes before expiry (default)
export BUCKET_AUTH_EARLY_INVALIDATION_SECS=300

# Disable the proactive buffer: refresh at expiry or on a 401 (set to 0)
export BUCKET_AUTH_EARLY_INVALIDATION_SECS=0

---

Hot Reload

Bucket picks up changes to ~/.bucket/auth.json automatically. If you update credentials externally (for example, with a script that writes new tokens), Bucket uses the new credentials on the next API call without a restart.

---

Auth Precedence

Bucket resolves credentials for each request in this order, highest to lowest:

1. Per-model api_key or env_key -- set under [model.<name>] in config.toml. Wins whenever present.
2. Active session token -- obtained through browser, OIDC/OAuth2, or external-provider login and stored in ~/.bucket/auth.json.
3. BUCKET_API_KEY -- fallback when no session token is active.

When more than one login flow is configured, Bucket populates the session token from the first available source, highest to lowest:

1. External auth provider (auth_provider_command)
2. Enterprise OIDC -- when OIDC is configured, through [bucket_com_config.oidc] in config.toml or the BUCKET_OIDC_ISSUER and BUCKET_OIDC_CLIENT_ID environment variables
3. SpaceXAI OAuth2 browser login -- the default

During a session, the active method handles all mid-session refreshes.

---

Related settings

/privacy does not change these config knobs:

Setting	How to set it
[features] telemetry	config.toml or BUCKET_TELEMETRY_ENABLED
[telemetry] trace_upload	config.toml or BUCKET_TELEMETRY_TRACE_UPLOAD
External OpenTelemetry	BUCKET_EXTERNAL_OTEL / [telemetry] otel_*. See Monitoring Usage.

On team accounts, only a team admin can toggle privacy with /privacy. Team admins can also enable or disable Zero Data Retention (ZDR) for their team. See How to enable ZDR. When ZDR is on, /privacy cannot change coding-data sharing.

See Monitoring Usage and Configuration.

---

Troubleshooting

Debug logging

Set RUST_LOG to control the verbosity of the file log and headless stderr output. (The TUI's on-screen tracing pane uses a fixed filter and ignores RUST_LOG.) In the TUI, file logging defaults to DEBUG; in headless mode (-p), RUST_LOG defaults to off so only the answer is printed — set RUST_LOG=error (or broader) to see logs on stderr.

In the TUI, set BUCKET_LOG_FILE to an absolute path to write logs to that file:

BUCKET_LOG_FILE=/tmp/bucket.log RUST_LOG=debug bucket
tail -f /tmp/bucket.log

BUCKET_LOG_FILE is treated as a literal file path. A relative value such as 1 writes a file named 1 in the current directory.

In headless mode, logs go to stderr. Redirect them to a file:

RUST_LOG=debug bucket -p "hello" 2> /tmp/bucket.log

Common log messages

Log message	What it means
auth: running external auth provider	Bucket is running your binary
auth: external auth provider returned fresh token	Bucket parsed and stored the token
auth: external auth provider failed	Binary exited non-zero or stdout was empty
auth: external auth provider timed out (likely needs interactive auth), killing	Binary did not exit before the timeout and was killed
auth: failed to start external auth provider	Command could not be spawned (binary not found)

Common fixes

• "Authentication failed" -- Run bucket logout to clear cached credentials, then bucket login to sign in again.
• Token expires too quickly -- Set auth_token_ttl or return expires_in in your auth provider's JSON output.
• OIDC redirect fails -- Ensure your IdP allows loopback redirect URIs (http://127.0.0.1/callback).
• External auth provider not found -- Check that the auth_provider_command path is correct and the binary is executable.