# API keys & routing

> Source: https://docs.xycai.us/keys.html  
> XycAi Developer Docs · Markdown edition for AI / LLM readers. Site index: https://docs.xycai.us/llms.txt

A key is a **routing rule**: it decides which vendors and models a request may reach and how the gateway chooses between pricing groups. Keys are created under [API Keys](https://www.xycai.us/keys) in the console and look like `sk-xxxxxxxx`.

## 1. Three routing modes

Choose a routing mode when creating the key:

| Mode | Reachable | Good for |
|---|---|---|
| **By vendor** default | Every model of the chosen vendor (Anthropic = all Claude models); smart routing inside that vendor's groups | Single-vendor clients such as Claude Code / Codex; one key per team or project |
| **By model** | Only the ticked models, across vendors; still routed to the cheapest available group | Restricting downstream systems or contractors to specific models |
| **All models and vendors** | Everything on the platform | Personal use, multi-model clients like Cherry Studio / Chatbox |

> **Vendor vs. model name**
>
> The `model` field says what to call; the key's routing mode says whether that model is **allowed** and **which group** serves it. Calling `gpt-5.6-terra` with an Anthropic-only key returns `403` — switch to an "all models" key or tick the model in "by model".

## 2. How smart routing picks a group

The same model often lives in several pricing groups (for example `claude-opus-5-5` in both Claude Enterprise and the coding-plan group). For every request the gateway:

1. **Sorts candidates by effective price** Candidates = groups available to your account that contain the model, ordered by discounted price ascending (ties by group order).
2. **Tries the cheapest first** If that group has no healthy channel for the model it moves up to the next one.
3. **Fails over automatically** Upstream errors are retried on another channel in the same group, then on the next group; you only see an error when everything failed.
4. **Falls back to special groups last** Models that only exist in Unlimited / Unreviewed groups are reached only when no regular group has them.

You normally **never pick a group by hand**; each usage-log entry shows the group and unit price that actually served the call.

## 3. The group system

Groups are the unit of pricing and upstream pools. Badges on the Models page mean:

| Group | Meaning | Examples |
|---|---|---|
| Enterprise | Official full-strength models, no client restrictions, long context, images and search; the main production tier | Claude / GPT / Gemini Enterprise, GLM / Kimi / DeepSeek / Qwen Enterprise |
| Economy | Discounted pools; GPT Economy is limited to Codex clients and cannot generate images, some pools do not guarantee cache hit rates | Claude / GPT / Gemini / GLM Economy |
| Edu | Promotional group excluded from automatic fallback; select explicitly | Claude Edu |
| Workflow | Official list price with the vendor's full catalogue (incl. legacy models); for non-coding toolchains and batch jobs | GPT / Claude / GLM / Gemini / Cohere / Mistral Workflow |
| Plan | Coding-plan subscriptions with their own concurrency and quota; falls back to the wallet when used up | Claude Code / Codex plans |
| Free | Free or promotional pools without availability guarantees; a positive balance is still required | DeepSeek Free, TypeSafe Free tier |
| Unreviewed | Third-party unreviewed image / video pools billed per image or per second | Seedream / Seedance / Qwen Image / Wan / MiniMax H3 / FLUX / LTX |
| Unlimited | Uncensored and abliterated models | GLM-5.3 / DeepSeek V4 Pro unlimited, Roleplay |

Discounts, per-model prices and tiered pricing live in the [model square](https://www.xycai.us/pricing), which is the source of truth.

## 4. Quota modes

| Mode | Behaviour |
|---|---|
| **Unlimited** | Bounded only by the account balance (default) |
| **Fixed total** | The key stops (`429`) once its lifetime spend reaches the cap; raise it any time in the console |
| **Periodic** | Resets daily / weekly / monthly; the period is anchored to the moment you saved the setting and resets once per full period |

Keys can also carry an **expiry date** and an **IP allow-list**; deleting a key revokes it immediately.

## 5. Concurrency and rate limits

- Concurrency is limited per **account tier**: untiered (T0) accounts get **30** in-flight requests, T1 and above **300**. Exceeding it returns `429` with an explanatory message.
- Coding-plan groups use the plan's own concurrency pool and do not stack with the above.
- Image generation has a separate concurrency gate so bursts cannot starve other traffic.
- Genuine high-concurrency needs (batch jobs, evaluations) can be unlocked per account — contact support with the use case. Pointless load testing is treated as an attack.

## 6. Account tiers and discounts

Accounts are tiered automatically by cumulative spend (T0 → T1 → T2 → V1 → V2); higher tiers get lower prices in each group, as shown in the model square's tier matrix. Tiers apply to every key on the account — no need to recreate keys.

## 7. Recommendations

- **One key per purpose**: Claude Code (by vendor: Anthropic), Codex (by vendor: OpenAI), chat client (all models) — isolated usage and spend.
- Give downstream systems a **by-model** key with a fixed or periodic quota.
- Keep keys server-side / in environment variables; proxy browser and mobile traffic through your own backend.
- `GET /v1/models` lists exactly what the current key can reach — the fastest way to debug a `403`.