Skip to main content
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

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

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

​
Commands

CommandDescription
auth login <provider>Store credentials. --method auto (default) picks OAuth if available, else API key
auth listShow stored providers with method + expiry
auth status [provider]Format check; --validate does a live call (uses a freshly-refreshed OAuth token)
auth logout <provider>Remove one provider
auth logout --allRemove all stored credentials

​
Login flags

FlagDefaultPurpose
--method auto|apikey|oauthautoForce a flow, or let the CLI pick
--key sk-…(prompt)API-key only; skip prompt
--key-stdinoffRead API key from stdin
--no-browseroffOAuth only; print URL + code instead of opening a browser
--base-url URL(default)Custom provider endpoint
--model NAME(none)Default model recorded with the credential
--skip-validationoffAPI-key only; skip the live check

​
Which --method should I use?

​
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

ItemValue
File~/.praisonai/credentials.json (unchanged from API-key flow)
Legacy fallback~/.praison/credentials.json is still read if the canonical file doesn’t exist yet; migrated onto the canonical file on the next write. No auth logout/re-login needed.
Permissions0o600, atomic writes
RefreshTransparent on next use, ~60 s before expires_at
Refresh failureCLI returns no token rather than a stale one — re-run auth login

​
Self-hosted / custom OAuth providers

praisonai auth login ships an empty built-in OAuth registry — production providers are added per release. To enable OAuth for a self-hosted gateway today, register a provider config from Python before invoking the flow: 
from praisonai.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",
)
Then: 
praisonai auth login my-gateway --method oauth

​
Headless / SSH

praisonai auth login acme --method oauth --no-browser
# To sign in, visit https://acme.example/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

​
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   Secret          Expires   Base URL      Model
# openai     apikey   sk-1***efgh     (n/a)     (default)     (none)
# acme       oauth    at-9***xyz1     59m       https://…     acme-large
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.
The auth list and auth status table columns changed in this release — two new columns (Method, Expires) were added. Scripts that parse the table output need to be updated. The --json output is additive only (no existing keys removed).

​
Credential Fields (ProviderCredential)

Each stored provider credential contains the following fields:
FieldTypeDescription
api_keystrStatic API key. For OAuth flows, mirrors access_token for backward compatibility
access_tokenstrOAuth access token (empty for API-key credentials)
refresh_tokenstrOAuth refresh token used for silent renewal
expires_atintUnix epoch seconds when the access token expires. 0 for API keys (no expiry)
auth_methodstr"apikey" or "oauth" — indicates which flow was used to store this credential
auth list and auth status show Method and Expires columns reflecting these fields.

​
Storage & Security

ItemValue
File~/.praisonai/credentials.json
Legacy fallbackRead-only fallback: ~/.praison/credentials.json. Any write transparently migrates its entries onto the canonical file.
Permissions0o600 (auto-corrected on read if loose)
WritesAtomic via temp file + os.replace
DisplayKeys/tokens redacted as at-9***xyz1 everywhere except the file
OAuth internalsrefresh_token, token_url, client_id are scrubbed before crossing into the LLM resolver — never sent to the provider
Path change — auto-migrated. Prior releases stored credentials at ~/.praison/credentials.json. The canonical path is now ~/.praisonai/credentials.json; the legacy path is still read if the canonical file doesn’t exist yet, and any subsequent auth login or setup transparently migrates your old entries onto the canonical file. No re-login is required.

​
Supported Providers

ProviderAPI key prefixEnv var injected at run timeOAuth supported today?
openaisk-OPENAI_API_KEY (+ OPENAI_BASE_URL if set)Not yet — use API key
anthropicsk-ant-ANTHROPIC_API_KEYNot yet — use API key
google / geminiAIGOOGLE_API_KEY / GEMINI_API_KEYNot yet — use API key
tavilytvly-TAVILY_API_KEYNot yet — use API key
groqgsk_GROQ_API_KEYNot yet — use API key
cohere(none)COHERE_API_KEYNot yet — use API key
Self-hosted / customn/a(your env var)Yes, via OAUTH_PROVIDERS registry override
Unknown providers accept API keys with length ≥ 10. OAuth is opt-in per provider.

​
Optional dependency

The OAuth flow uses the requests library. It is lazy-imported, so users on the API-key path never see it. If a user runs --method oauth without it installed: 
OAuth login requires the optional 'requests' package. Install it with: pip install requests

​
How Run Uses Credentials

praisonai run resolves credentials in this order:
  1. Environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, …)
  2. Stored credentials — OAuth tokens refreshed transparently (~60 s before expiry) before injection
  3. LLM endpoint resolution via resolve_llm_endpoint_with_credentials
If an expired OAuth token cannot be refreshed (refresh token revoked, network error, etc.), praisonai run reports: 
Error: No valid token for <provider>. Run: praisonai auth login <provider> --method oauth
If nothing is found, non-interactive mode exits with: 
Error: No API key configured. Run: praisonai auth login
See Run for the interactive wizard path.

Run

Preflight credential check before execution

Config

Default model via [llm] in config.toml

Setup

First-run setup wizard