Auth

Store and manage LLM provider credentials securely — API keys or browser-based OAuth

praisonai auth stores provider credentials locally so praisonai run works without exporting env vars every session. Two methods are supported: a long-lived API key, or a short-lived OAuth token signed in via your browser.

Quick Start

# Omit the provider to pick from the model catalogue (~30+ LLMs)
praisonai auth login
# → Choose your LLM provider: openai | anthropic | google | ollama | ... | custom

praisonai run "What is 2+2?"

# Interactive — key is hidden at the prompt
praisonai auth login openai

# Then run immediately
praisonai run "What is 2+2?"

# Device-code flow; sign in; tokens stored + auto-refreshed
praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id>

praisonai run "What is 2+2?"

# Prints a URL + code instead of opening a browser
praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id> --no-browser
# To sign in, visit https://github.com/login/device and enter code: ABCD-EFGH

praisonai run "What is 2+2?"

Commands

Login flags

Which --method should I use?

Provider Picker

Omit the provider argument and auth login opens a catalogue-driven picker so you never have to memorise a provider id.

praisonai auth login

Choose your LLM provider:
  1) openai
  2) anthropic
  3) google
  4) ollama
  5) groq
  6) openrouter
  7) mistral
  ...
  N) Other/custom
Select provider [1]:

The list comes from ModelCatalogue.list_providers(): openai, anthropic, google, ollama first, every other catalogue provider appended, custom last. Picking custom prompts for a free-form provider id. The positional <provider> argument still works unchanged — keep passing it in scripts and CI.

OAuth Login (browser-based)

Two flows are negotiated automatically per provider:

• Device code (RFC 8628) — prints a short code + URL, polls until you approve. Default on headless servers.
• Authorization code + PKCE (RFC 7636) — opens your default browser and listens on 127.0.0.1 for the redirect. Default on desktops.

The OAuth callback handler and PKCE helpers are shared with the MCP OAuth integration.

Token storage & refresh

Self-hosted / custom OAuth providers

praisonai auth login ships built-in endpoints for github, google, gemini, and azure. For a provider outside the registry (e.g. a self-hosted gateway), supply the endpoints directly with CLI flags:

praisonai auth login my-gateway --method oauth \
  --client-id cli \
  --device-authorization-url https://gateway.example.com/oauth/device \
  --token-url https://gateway.example.com/oauth/token \
  --scope "read write"

The CLI infers the device flow when a --device-authorization-url is present, or falls back to authcode (PKCE) when you pass --authorization-url instead.

As an escape hatch, you can also register a provider config from Python before invoking the flow:

from praisonai_code.cli.configuration.oauth import OAUTH_PROVIDERS, OAuthProviderConfig

OAUTH_PROVIDERS["my-gateway"] = OAuthProviderConfig(
    flow="device",
    client_id="my-client-id",
    token_url="https://gateway.example.com/oauth/token",
    device_authorization_url="https://gateway.example.com/oauth/device",
    scope="read write",
)

Headless / SSH

praisonai auth login github --method oauth --client-id <your-github-oauth-app-client-id> --no-browser
# To sign in, visit https://github.com/login/device and enter code: ABCD-EFGH

API Key Login

praisonai auth login openai
praisonai auth login openai --key sk-...
echo "sk-..." | praisonai auth login openai --key-stdin

# Optional extras
praisonai auth login openai --key sk-... --base-url https://api.openai.com/v1 --model gpt-4o
praisonai auth login openai --skip-validation

Replacing an existing key

The store holds one credential per provider, so auth login never overwrites a different stored key silently.

praisonai auth login openai
# Enter API key for openai: ****************
# API key validated: live call ok
# Replace existing openai key sk-o***1111? [Y/n]: n
# → exits with status 1; the old key is kept

praisonai auth login openai --key sk-new-...2222
# API key validated: live call ok
# Replacing existing openai key sk-o***1111
# Stored credentials for openai
# Key stored: sk-n***2222

praisonai --json auth login openai --key sk-new-...2222

{
  "provider": "openai",
  "status": "stored",
  "key_redacted": "sk-n***2222",
  "replaced_key_redacted": "sk-o***1111"
}

List & status

praisonai auth list
praisonai auth status
praisonai auth status openai --validate

Logout

praisonai auth logout openai
praisonai auth logout --all

List & Status — new columns

praisonai auth list
# Provider   Method   Source                   Secret          Expires   Base URL      Model
# openai     apikey   env (OPENAI_API_KEY)      sk-1***efgh     (n/a)     (default)     (none)
# anthropic  apikey   stored                   sk-a***wxyz     (n/a)     (default)     (none)
# groq       apikey   env (GROQ_API_KEY)        gsk_***abcd     (n/a)     (default)     (none)
# github     oauth    stored                   at-9***xyz1     59m       (default)     (none)

Source shows where the live credential comes from: stored (from ~/.praisonai/credentials.json) or env (VARNAME) when an active environment variable is present. An env key that shadows a stored one is flagged env (VARNAME) [live, overrides stored].

Expires shows (n/a) for API keys, 59m, 1h 23m, <1m, or expired for OAuth tokens, and (no expiry) when the provider didn’t include one.

Stored vs environment credentials

auth list and auth status surface both stored credentials (from ~/.praisonai/credentials.json) and active environment-variable keys for catalogue-known providers. The Source column disambiguates them:

When PRAISONAI_AUTH_CONTENT is set, every stored-side entry reports env (in-memory) instead of stored:

praisonai auth list
# Provider   Method   Source            Secret          Expires   Base URL   Model
# openai     apikey   env (in-memory)   sk-1***efgh     (n/a)     (default)  (none)
# github     oauth    env (in-memory)   gho_***xyz1     59m       (default)  (none)

If both a stored and an env credential exist for one provider, the env value wins at run time (this is unchanged) — the Source line appends [live, overrides stored] so it’s visible:

praisonai auth list
# Provider   Method   Source                                       Secret          Expires   Base URL   Model
# openai     apikey   env (OPENAI_API_KEY) [live, overrides stored] sk-1***efgh     (n/a)     (default)  (none)

Both stored and env secrets are redacted the same way (sk-1***efgh).

Credential env-var aliases

Some providers declare more than one credential env-var spelling — Together’s TOGETHER_API_KEY / TOGETHERAI_API_KEY, Fireworks’ FIREWORKS_API_KEY / FIREWORKS_AI_API_KEY, Google’s GOOGLE_API_KEY / GEMINI_API_KEY. auth list and auth status recognise every alias — a key set under a secondary spelling is surfaced exactly like one set under the canonical first.

export TOGETHERAI_API_KEY=sk-1234abcdefgh
praisonai auth list
# Provider   Method   Source                     Secret          Expires   Base URL   Model
# together   apikey   env (TOGETHERAI_API_KEY)   sk-1***efgh     (n/a)     (default)  (none)

The Source column names whichever alias is live in the environment, so it always tells you exactly which variable the runtime is reading — even when a secondary spelling is the one you set. If no alias is set but the provider is otherwise referenced, the canonical first var name is shown for display only.

Credential Fields (ProviderCredential)

Each stored provider credential contains the following fields:

auth list and auth status show Method and Expires columns reflecting these fields.

Storage & Security

Zero-disk mode (PRAISONAI_AUTH_CONTENT)

Set PRAISONAI_AUTH_CONTENT to a JSON credential store and PraisonAI runs entirely from memory — nothing is ever read from or written to ~/.praisonai/credentials.json.

Use it for ephemeral containers (Docker/Kubernetes), CI runners, and secret-hygiene-sensitive deployments where OAuth and refresh tokens must not touch disk. A single secret injects the whole store — including OAuth entries — with zero on-disk footprint.

The value is a JSON object mapping provider name → credential object. Each credential object mirrors the on-disk ProviderCredential fields — api_key and auth_method for API keys, plus access_token, refresh_token, and expires_at for OAuth:

{
  "openai": {
    "api_key": "sk-...",
    "auth_method": "apikey"
  },
  "github": {
    "api_key": "gho_...",
    "auth_method": "oauth",
    "access_token": "gho_...",
    "refresh_token": "ghr_...",
    "expires_at": 1723545600
  }
}

# Inject the store from a CI secret; nothing is written to disk
export PRAISONAI_AUTH_CONTENT='{"openai":{"api_key":"sk-...","auth_method":"apikey"}}'
praisonai run "What is 2+2?"

import json, os
from praisonaiagents import Agent

os.environ["PRAISONAI_AUTH_CONTENT"] = json.dumps({
    "openai": {"api_key": "sk-...", "auth_method": "apikey"},
})

agent = Agent(name="CI Agent", instructions="Answer briefly")
agent.start("What is 2+2?")
# No ~/.praisonai/credentials.json is created — everything stays in memory.

Invalid values fail fast rather than silently falling back to disk, protecting the zero-disk contract:

auth list and auth status report the Source column as env (in-memory) in this mode via the CredentialStore.is_in_memory property, so zero-disk runs are never silently invisible.

Supported Providers

praisonai auth list / praisonai auth status recognise every provider in PROVIDER_ENV_CATALOGUE — the same catalogue that drives first-run credential detection (full 14-row table) and praisonai setup.

_API_KEY` (derived) | (your model) | Not yet — use API key |

Unknown providers accept API keys with length ≥ 10. OAuth is opt-in per provider; registry providers ship endpoints but no client_id — pass yours with --client-id.