Roo Code API Key Setup: Multi-Model, Security, and Teams (2026)

A Roo Code API key determines which provider handles requests, which models are available, whose account pays, and how far the damage spreads if it leaks. Many cases of "the key stopped working" are actually a wrong Base URL, model name, or provider type.

This article gives a practical process in the order of creation, compatible configuration, multi-model profiles, key security, rotation, team policy, and troubleshooting. After migrating to the community fork Zoo Code, most of these concepts still apply.

Note: Roo Code is a trademark of its owner, and VS Code is a trademark of Microsoft. This article is a technical note and implies no affiliation with the vendors. The Roo Code extension stopped maintenance on May 15, 2026, and the repository was archived the same day; defer to the official repository and documentation for current status. Models and prices are subject to the on-site model pricing.

1. Confirm your situation and key type

Roo Code is an open-source AI coding agent for VS Code that uses a bring-your-own-key (BYOK) model: the extension does not resell model access, and calls are billed to the provider key you enter. It supports multiple providers as well as OpenAI-compatible endpoints.

The current status needs to be stated first: according to public information, the Roo Code extension stopped maintenance on May 15, 2026, and the original repository was archived. There will be no further feature updates, bug fixes, or security patches. Existing installations usually still run, but long-term use should count the lack of patches as a risk. The community fork Zoo Code continues development from the original code under the Apache-2.0 license.

"Roo Code API key" usually means a provider key, a gateway-compatible key, or the address configuration for a local model such as Ollama. This article covers the second case; it is not used to sign in to Roo Code and cannot call its cloud services.

2. Create a key: define the boundary first

Before creating a key, decide who will use it, which project it belongs to, and the maximum it may spend. These three answers determine how quickly you can locate and contain a problem.

Open the ZSQH AI Gateway sign-up page, register, and sign in to the console.
Go to the API Keys page and click create.
Name it by user and device, for example roo-zhang-macbook, not just test.
Set a spending cap and expiration date; give a test key a low quota first.
If the console supports model scoping, select only the models actually needed.
Copy the full key into a password manager; most consoles show it in full only once.

Keys often start with sk-, but the prefix proves nothing about authenticity or permissions. Watch for leading or trailing spaces and line breaks when copying; these are a frequent cause of Invalid API Key.

3. Configure the OpenAI-compatible endpoint

The path is Settings → Providers; set API Provider to OpenAI Compatible. Only three fields are essential:

Base URL: enter a root address such as https://ai.zhongshangqihang.com/v1, not the website homepage and not a path ending in /chat/completions.
API Key: paste the gateway key you just created.
Model: enter the exact model ID shown on the pricing page; do not guess a suffix.

Expanding Model Configuration also lets you set Max Output Tokens, Context Window, Image Support, Computer Use, Input Price, and Output Price. The last two are only for local cost estimates and do not change actual billing; do not overstate the context window, or long tasks may fail.

Roo Code relies on the model's native tool calling, with no XML fallback. A compatible endpoint must not only chat but also support OpenAI-style function calling; otherwise ordinary conversation works and the agent fails as soon as it invokes a tool.

curl https://ai.zhongshangqihang.com/v1/chat/completions \
  -H "Authorization: Bearer $ZSQH_ROO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model ID>","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

If curl works but Roo Code reports an error, check whether the Base URL has an extra path, whether the model ID matches, and whether the model supports tool calling.

4. API Configuration Profiles: the core of multi-model work

API Configuration Profiles are saved, switchable sets of model configuration. Each profile independently stores the provider, key, model, temperature, thinking budget, rate limit, and diff-editing settings. This is the feature most worth learning first for a multi-model workflow.

In Settings → Providers, click the + next to the profile selector, name the profile, choose the provider, enter the key, select the model, and set a Rate Limit if needed. Rate Limit is the minimum interval between two requests for that profile and is off by default. Profiles can be switched in the settings panel or from the API Configuration dropdown in the chat interface.

Finer control lives on the Prompts tab: each mode can be bound to a profile. A task locks in the profile it started with, including when restored from history; Orchestrator subtasks inherit the parent profile and keep it for their whole lifecycle. So do not bind Orchestrator to an expensive model and then expect subtasks to downgrade.

Profile name	Purpose	Model tier	Key policy	Notes
`plan-strong`	Architecture, complex refactors	Strong reasoning model	Separate key, higher cap	Bound to Architect
`code-daily`	Daily coding, bug fixes	Main model	One per person	Bound to Code
`ask-cheap`	Code Q&A, explanations	Lightweight model	Low-quota key	Bound to Ask
`batch-cheap`	Bulk comments, formatting	Low-cost model	Project-specific key	Rate-limited
`backup`	Switch when the primary fails	Backup model	Separate key	Verify regularly

Name profiles as "scenario-tier" for easy checking. Model IDs and prices change, so defer to model pricing.

5. Key security: storage, permissions, and data boundaries

According to the documentation, keys are stored in VS Code Secret Storage and are not written in plaintext to ordinary settings files. That is not absolute safety: protection depends on the operating-system account, and anyone who can sign in to your computer, or any process with your permissions, may still reach the key.

Several further steps are needed: use a separate system account on development machines and avoid long-term key storage on shared computers; define an extension allowlist on company devices; confirm the settings-sync scope and do not sync sensitive configuration to uncontrolled devices; never paste keys into prompts, code comments, or terminal history; mask key fields before taking screenshots; and choose channels by data classification, because code context is sent to the service behind the Base URL.

Least privilege aims at "a bounded loss even if leaked": set a quota, expiration, and model allowlist, and enable IP allowlisting or project scoping if the gateway supports it. Use three keys for testing, daily work, and automation; do not use one key for everything.

6. Rotation, revocation, and incident handling

Rotate every 90 days, or immediately when a member leaves, a device is lost, or a leak is suspected. Roo Code is no longer maintained, so older versions receive no security patches and the cycle can be more conservative.

The safe order is "run in parallel, switch, then disable": create a new key with a date suffix; store it in the password manager while keeping the old key temporarily; replace it in the profile and test; confirm the gateway log shows records for the new key; watch the error rate for a day or two; then disable the old key.

If a leak is confirmed, reverse the order: disable or delete the key first, then look at abnormal usage, source, and time window, and then inspect repository history, logs, and chat records. Contain the damage first; do not begin by reconstructing the leak path.

7. Team use: turn personal settings into policy

Roo Code keys live on each developer machine, so a team relying only on the extension cannot easily see who uses which key. Central control belongs at the gateway: one key per person, keys split by project, unified quotas, and retained request logs.

Named keys: include the member and purpose in the name, disable on the day someone leaves, and never share a "team key".
Project isolation: separate keys and quotas for production, experiments, and automation.
De-key the workspace: keep only the Base URL, model name, and mode notes in the repository; leave the key in user-level storage.
Separate accounts for shared services: CI, scripts, and bots use service keys, not member keys.
Monthly audit: check for unused keys, abnormal quotas, and sudden spikes in authentication failures.
Least permission: do not assign strong models to lightweight scenarios, and do not allow automatic terminal execution for read-only tasks.

Auto-approve improves efficiency but also amplifies mistakes and token consumption; teams should state which commands always require human confirmation.

8. Common troubleshooting

Invalid API Key: the key is incomplete, contains spaces, or was entered into an Anthropic- or Gemini-specific provider. Switch to OpenAI Compatible and retry.
Model Not Found / 404: a typo in the model ID, or the Base URL includes /chat/completions. Copy the ID verbatim from the pricing page and keep the Base URL only through /v1.
401 / 403: the key is disabled, the quota is exhausted, or the model is not permitted. Check the console status and usage first.
429: a rate limit or quota cap was hit. Reduce concurrency and check the Rate Limit and key quota.
Chat works but tool calls fail: the endpoint or model does not support native function calling. Switch to a model or endpoint that supports tool calls.
A long task fails midway: the context window is overstated or the output limit is unreasonable. Enter the real capability.

Troubleshoot at three levels: check the provider, Base URL, and model name; reproduce with curl; and check whether the gateway log has the corresponding request. When all three line up, the key is usually not the problem.

FAQ

Can Roo Code still be used?

Installed copies usually still run, but the original team stopped maintenance on May 15, 2026, and the repository is archived, with no further updates or security patches. New projects should evaluate Zoo Code or another maintained tool; if you keep using an older version, restrict key permissions.

Where is the key stored?

According to the documentation, it is stored in VS Code Secret Storage and not written in plaintext to ordinary settings files. It is still a local credential whose protection depends on the system account and machine security. Shared devices should use separate accounts and avoid syncing sensitive configuration.

Can one key serve multiple profiles?

It can, but it is not advisable. Different profiles use different models and quotas, and separate keys make users and scenarios visible in logs; with one key, it is also hard to judge the blast radius when something goes wrong.

Why does chat work but the agent's tools fail?

Roo Code uses only native tool calling, with no XML fallback. The compatible endpoint must implement OpenAI-style function calling and the model must support it. Test with a model that supports tool calling first, then decide whether the endpoint or the model is at fault.

Not recommended. A shared key cannot separate usage, and it is hard to revoke after someone leaves. Use one key per person, create separate keys for CI or shared services, and set quotas and alerts centrally at the gateway.

Summary

If you still use Roo Code or Zoo Code, create a low-quota test key first, verify it once with curl and once with a real agent task, and then distribute keys to the team. Start from the sign-up page; see model pricing for models, quotas, and billing, which change with model versions and upstream policy.