API Keys & Routing Groups
Applies to: Organization (top-level user), Subuser, Developer Updated: 2026-07-02
An API Key is the credential for calling models. In the new console, each Key is bound to one "routing group": when you call with a bare model name, the request goes to the group bound to that Key. This article explains how to create, configure, and manage Keys, and how routing works at call time.
For how to write call names (bare name vs. fingerprint) and the dual-routing rules, see Developer Guide · Call Guide & Dual Routing.
1. The Key Routing Model: Each Key Is Bound to One Group
When creating / editing a Key, choose a routing group for it:
- Routing group (single select): when this Key is called with a bare model name (no fingerprint), the request routes to that group. The options are the groups currently available to you (a subuser only sees the groups the organization has authorized to it).
- Consequence of not binding: if no routing group is selected, this Key cannot be called with a bare model name (it will be rejected); in that case you can only use a fingerprinted call name to target a specific group.
- Binding one Key to one group continues the legacy behavior of "one group per Key," requiring zero changes to legacy clients.
What is a group? A group is like a service-package label — the same model can be offered through different groups, and different groups may correspond to different channels, prices, and discounts. Groups are maintained uniformly by the platform, and you can see the currently available groups on the "Call Guide" page. See Platform Overview · Multi-Channel Service System & Groups.
Advanced: dispatch group allowlist (optional, organization-configurable only) Beyond the routing group, an Organization (top-level user) can also configure a "dispatch group allowlist" for a Key, to constrain which groups fingerprinted / targeted calls can reach. It coexists with the routing group: bare names go to the bound routing group; fingerprinted / targeted calls are additionally constrained by the allowlist. This is an advanced item, not configurable by subusers, and unnecessary in most scenarios.
2. Who Can Create Keys
| Role | Can create Keys | Description |
|---|---|---|
| Organization (top-level user) | ✅ | Can create Keys and configure routing groups and the advanced allowlist |
| Subuser | ✅ | Can self-create Keys; the routing group can only be chosen within the organization's authorized scope; cannot configure the advanced allowlist |
- Both organizations and subusers can self-create Keys on the "API Keys" page (
/keys). - When a subuser creates a Key, the routing group dropdown lists only the groups the organization has authorized to it; the advanced allowlist field is not shown to subusers.
- All Keys under a subuser share the same quota limit (i.e., the cumulative consumption count against the quota limit), and actual deductions always come from the balance of its organization (parent account) — see Subuser Management.
- On the Key page, a subuser also has a "subuser quota card" at the top, which read-only displays its quota status.
3. Creating / Editing a Key
- Go to the "API Keys" page (
/keys) - Click the "Create Key" entry
- Configure the following:
| Configuration item | Description |
|---|---|
| Name / Note | Helps identify the Key's purpose |
| Routing group | Single select. When called with a bare model name, routes to this group; if not selected, the Key cannot be called with a bare name. Options are narrowed by your authorized scope |
| Dispatch group allowlist | Advanced, optional, visible to organizations only. Constrains which groups fingerprinted / targeted calls can reach |
| IP blacklist / allowlist | Restricts the source IPs that can use this Key (optional) |
- After submission, keep the generated Key safe
4. Key List Display
The "API Keys" page list displays key information for each Key:
| Column | Description |
|---|---|
| Masked Key | Shows only some characters, protecting the full key |
| Routing group | Shows the name of the bound group and discount info; if unbound, prompts you to select a group. Supports inline switching of the bound group within the list |
| IP blacklist / allowlist | Uses a shield icon to indicate whether IP restrictions are configured |
| Quota / rate limit | Shows the Key's quota and rate-limit window (if any) |
| Status | Whether the Key is currently usable |
The list's "Routing group" column allows switching the bound group inline directly (the switch scope is likewise constrained by authorization), without entering the edit dialog.
5. How Routing Works at Call Time
At call time, the model name can be written in two ways, with different routing behavior:
| model called | Routing behavior |
|---|---|
With fingerprint (e.g., 5MHXZWKA/gpt-4o) | Parse the fingerprint → fixed routing to the group that fingerprint corresponds to |
Bare model name (e.g., gpt-4o) | Routes to the routing group bound to this Key (V1 behavior) |
- A bare model name goes to the Key's bound group; if the Key is not bound to any group, a bare-name call is rejected (
403) — in that case switch to a fingerprinted call name, or bind a routing group to the Key first. - Call names are obtained and copied uniformly on the "Call Guide" page; see Call Guide & Dual Routing
- When the selected channel is unavailable, it errors out directly — no automatic channel switching, no downgrade, no fallback
6. Legacy Key Compatibility
After the new version goes live, legacy Keys remain valid and calls are uninterrupted:
- Legacy Keys still work by their original bound group, behaving as in the legacy console — which is entirely consistent with the new "one group per Key" model
- Legacy clients and legacy scripts require zero changes; keep using bare model names
- To target another group, copy a fingerprinted call name from the "Call Guide"
For migration-related notes, see Migration & Transition Notes.
7. FAQ
Q: How do I choose a group when creating a Key? A: Select a group under "Routing group," and this Key will use it when called with a bare model name. If you don't select one, this Key can only use fingerprinted call names.
Q: Can one Key go to multiple groups at once? A: A bare model name always goes to the one bound routing group. To temporarily target another group, use a fingerprinted call name (constrained by the advanced allowlist configured by the organization).
Q: Can subusers create their own Keys? A: Yes. On the "API Keys" page, a subuser can self-create Keys; the routing group can only be chosen within the organization's authorized scope. All Keys under a subuser share the same quota limit, and charges deduct from the organization balance.
Q: What should I put in the model field at call time? A: Copy it from the "Call Guide." A fingerprint routes by the group the fingerprint corresponds to; a bare name goes to this Key's bound group. See Call Guide & Dual Routing.
Q: If a channel is unavailable, will it switch to another automatically? A: No. When the selected channel is unavailable, it errors out directly — no automatic switching, no downgrade, no fallback.
Q: How do I restrict the source IPs of a Key? A: Configure the IP blacklist / allowlist when creating / editing the Key; the list will mark it with a shield icon.
Q: What if a Key is lost or I suspect it was leaked? A: On the "API Keys" page, find the Key, click disable or delete, then create a new Key. A disabled or deleted Key becomes invalid immediately and cannot be recovered.
Contact Us
- Email: support_cloudrouter@clouditera.com
- QQ community: 712273971
- Website: cloudrouter.online