API keys and model accounts

ORG-2 does not resell inference. Every model call is paid for by an account you connect yourself: a provider API key you paste in, or a subscription you already have with an agent CLI such as Claude Code, Codex, or Cursor. Both live in the same place, are stored on your machine, and are picked per session. This page covers every provider ORG-2 knows about, the fields for each, and what happens to a key after you save it.

Where keys live in the app

Open Settings → Models & Keys. The page is titled Models & CLIs and its own help text is explicit: "Add API keys and configure CLI agents. Keys are stored locally and never leave your machine."

Three tabs run across the top:

• Models — every model your connected accounts expose, with a toggle per model.
• My Keys — the accounts themselves. Add Account starts the wizard.
• Model Wiki — a reference catalogue of models, independent of what you have connected.

A separate CLI Clients view lists each agent CLI with whether it is Installed, its Keys status (Configured / Not configured), the method it was Installed via, and its install and uninstall scripts. Add Agent starts the same wizard pre-filtered to CLIs. An On prem view covers local runtimes.

Two ways to pay for a model

ORG-2 distinguishes an API key account from a Subscription account, shown as the Auth Method on every account row:

• API Key — a secret you paste. ORG-2 calls the provider's HTTP API directly with it. Works with both ORG-2's own Rust agents and, where the CLI supports it, with an external CLI.
• OAuth — you sign in to an existing plan and ORG-2 stores the resulting token locally. The Auth Method field spells out the variant: OAuth (ChatGPT Login), OAuth (Session Capture), OAuth (GitHub PAT), OAuth (AWS SSO).

The difference is billing and scope. An API key is metered per token by the provider. A subscription reuses a plan you already pay for — signing in with Claude Code, for example, saves a claude_code OAuth account that ORG-2's own Rust agents can use through the native Anthropic protocol, not just the claude binary. A Quota Info panel shows plan, used, limit, and reset date for providers that report them.

Supported model providers

Each API provider has a default endpoint, a conventional environment-variable name (shown in the wizard as Environment variable:), and a wire protocol. All of them accept a custom base URL.

The two Azure entries have no default endpoint — you supply the resource URL (AZURE_OPENAI_ENDPOINT / AZURE_ANTHROPIC_ENDPOINT) and enter your deployment names under Deployment Models.

Supported agent CLIs

"Compatible API keys" is what the CLI row's Compatible API Keys section lists: a CLI counts as configured if you hold either its own subscription account or a key for one of those providers.

Add an API key

1. Go to Settings → Models & Keys → My Keys and press Add Account.
2. Pick a Model Provider. Optionally set an Account Name — leaving it blank uses the provider name, then Provider-1, Provider-2, and so on. Duplicate names are rejected.
3. Paste the key into API Key ("Secret key used to authenticate requests to the provider's API").
4. Leave Base URL on Official URL unless you are proxying (see below).
5. Press Validate. On success you get either "{n} models detected — configure in next step" or "Key validated — no models auto-detected, please add models manually below".
6. Enable the models you want in the table, then Complete.

If auto-detection finds nothing — common with proxies that do not implement /v1/models — a Manual Models table appears where you map a Canonical Name to the Model Alias your proxy expects. Custom Models lets you add arbitrary ids with an optional display name and icon.

Add a CLI subscription

Switch to CLI Clients, press Add Agent, and choose the CLI. The Setup Method step offers a subset of:

• Sign In — a browser flow inside the app. Sign in with Claude Code, Sign in with Codex (ChatGPT Plus/Pro), and Sign in with Gemini all capture the callback and store the OAuth token locally. Cursor uses a Guided Setup with the internal browser, followed by a User API Key generated in Cursor's dashboard.
• Autodetect — "Scan local config files and environment variables". Codex reads ~/.codex/auth.json and OPENAI_API_KEY; Gemini reads ~/.gemini/oauth_creds.json and GEMINI_API_KEY; Anthropic detection checks ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, then ~/.claude.json, ~/.claude/config.json, ~/.config/claude/config.json, ~/.config/anthropic/config.json, then ~/.zshrc, ~/.bashrc, ~/.bash_profile, ~/.profile; Cursor reads its state.vscdb; Kiro reads kiro-cli local storage. If several are found you get a Multiple keys found picker.
• Enter Key / Enter Token — paste directly. GitHub Copilot needs a PAT starting github_pat_ with Copilot Chat, Editor Context, and Requests enabled.
• Extract Config — paste messy text (a config file, a chat message) and let ORG-2 parse the key and base URL out of it.

Environment variables are a detection source, not a runtime fallback. Once saved, ORG-2 always reads the stored account; it does not silently pick up OPENAI_API_KEY from your shell at session time. When it launches an external CLI it injects the stored values back out as that CLI's own variables — ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL, OPENAI_API_KEY / OPENAI_BASE_URL, GEMINI_API_KEY / GOOGLE_GEMINI_BASE_URL, CURSOR_API_KEY, GH_TOKEN, KIRO_API_KEY, MOONSHOT_API_KEY / MOONSHOT_BASE_URL.

Custom base URLs, proxies, and local models

Press Add custom base URL (Optional) to switch from Official URL to Custom URL. The app warns you, and the warning is worth repeating:

Warning: Using a custom base URL may expose your API key and data to third-party servers. Only use this for trusted proxies, self-hosted deployments, or known secure endpoints.

For local inference, use the vLLM / Local provider, which opens a Local model cookbook: pick a Runtime preset — Ollama (port 11434), LM Studio (port 1234), vLLM (port 8000), llama.cpp (port 8080), or Custom — and the endpoint and starter model ids are filled in for you. Most local runtimes accept any non-empty API key, so keep the placeholder unless your server enforces one. Start the runtime first, then validate; or add model ids by hand and save without validating.

Keys are global; accounts are per session

There is one key store per installation. Keys are not scoped to a repo, a workspace, or an agent — an account you add is visible everywhere. What varies is which account a given run uses:

• Per session. The model selector is laid out as Models on the left and Accounts on the right, so after choosing a model you choose the key that pays for it. It shows Choose a key or No compatible keys.
• Per agent. An agent definition carries a preferred account and a preferred model (plus an optional faster Summarization Model), configured in the agent's own settings rather than here.
• Per model. Each account exposes a set of models you can enable or disable individually, plus a master Enable key switch. A disabled account contributes nothing, even if something targets it explicitly.

Storage, and whether keys leave your machine

Accounts are written to ~/.orgii/credentials.json (relocatable with the ORGII_HOME environment variable). The file is written atomically — to a temp file, permissions applied, then renamed — and ends up mode 0600 on macOS and Linux, or a restricted ACL on Windows.

Warning: Secrets are stored as plaintext JSON. ORG-2 does not use the OS keychain, Windows Credential Manager, or the Linux Secret Service, and does not encrypt this file at rest. The file mode is the only protection, so any process running as you can read it. See Security and privacy.

Keys are used to call your provider directly from your machine. They are not proxied through ORG-2 and are never included in cloud sync. Displayed values are masked to the first and last four characters.

Rotate, disable, and remove

There is no in-place key edit. Edit Account renames and re-describes an account only, and says so: "To update your API key, keys, or provider settings, remove this account and add a new one." To rotate, add the new account, confirm it validates, then remove the old one.

• Revalidate — "Check if this key is working again", after fixing something upstream.
• Enable key — a master switch that parks an account without deleting it.
• Remove Local — deletes the locally saved key; the confirmation warns if active sessions still use it, since those will fail on their next turn.

Troubleshooting authentication

"Invalid keys" / "Suspended - API key failed". A 401 or 403 from the provider marks the account invalid. Re-check the key at the provider, then add a fresh account. Health is tracked per key as valid, degraded, invalid, or unknown, and the row shows the last validation error.

Some models fail, others work. That is the Degraded key state — "{n} model(s) unavailable. Only {m} model(s) working." Disable the failing models or re-run Auto-detect.

An OAuth subscription stops working. Tokens are refreshed automatically. A refresh that fails transiently backs the account off for about five minutes; a permanent failure (invalid_grant, expired or revoked refresh token) disables the account after three consecutive failures. Re-run the sign-in flow. Provider outages park a key for up to 30 minutes; rate limits record a reset time.

No models detected after a valid key. Your endpoint probably does not implement a model-list route. Add the models manually — the key itself is fine.

Corporate proxy or TLS interception. A custom base URL sends your key to that host, so only point it at something you trust. For network-level problems — proxies, VPNs, HTTP version — see Troubleshooting.

Region warnings. ORG-2 detects your region and may show "{provider} may not be officially available in your detected region." Setup still proceeds; some models may not be listed.

Next steps

• Agents — which agent uses which account, and how ORG-2 drives external CLIs.
• Sessions — choosing a model and account when you start work.
• Security and privacy — what is on disk and what is transmitted.
• Troubleshooting — symptom-by-symptom fixes.