# Core concepts

Source: https://platform.lyrouter.com/ai_gateway/docs/concepts/en
Last updated: 2026-10-22

To use LYRouter, first keep three layers apart: the account and workspace decide who owns resources, the API key decides who is calling, and the model and its service source decide which upstream the request finally goes to. This page introduces the concepts used throughout the documentation, and the steps a request goes through in the gateway.

## Accounts, workspaces and API keys

| Concept | Description | Details |
| --- | --- | --- |
| Account | Personal, Team or Enterprise. Subscriptions, the Credits balance and members all belong to an account; one user can belong to several accounts at once and switches between them at the top of the console | [Teams, members and roles](https://platform.lyrouter.com/ai_gateway/docs/organization/en) |
| Member roles | An account has only two roles, Owner and Member. The Owner manages members, subscriptions and all workspaces; a Member can enter only the workspaces they are granted | [Teams, members and roles](https://platform.lyrouter.com/ai_gateway/docs/organization/en) |
| Workspace | The unit within an account that isolates application environments. Enabled models, API keys, BYOK, routing settings and request logs are all scoped to a workspace. Roles within a workspace are Viewer, Editor and Admin | [Workspaces and API keys](https://platform.lyrouter.com/ai_gateway/docs/api-keys/en) |
| API key | The credential an application uses to call the gateway; it belongs to one workspace. The plaintext is shown only once, when the key is created; you can set an expiry time, budgets and an IP allowlist | [Workspaces and API keys](https://platform.lyrouter.com/ai_gateway/docs/api-keys/en) |

What you enter in a client is always a LYRouter API key. API keys you obtain from a provider are for BYOK: configure them in the console, and do not enter them in a client.

## Models and service sources

| Concept | Description | Details |
| --- | --- | --- |
| Model ID | The value of the `model` field in a request, such as `deepseek/deepseek-v4-flash`. Copy it from the workspace's **Model marketplace**, or query `GET /v1/models`; do not use the model's display name | [Choosing a model](https://platform.lyrouter.com/ai_gateway/docs/choose/en) |
| Service source | A model can be served by a platform source (the platform's provider accounts, billed in Credits) or a BYOK source (your own provider account), and both can exist at the same time | [Platform models or BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok-choice/en) |
| Provider and channel | A provider is the identity of a model vendor; a channel is one specific access point of that provider, including its address, protocol and access mode. A provider's pay-as-you-go API and its Coding Plan are two channels | [Channels and routing](https://platform.lyrouter.com/ai_gateway/docs/routing/en) |
| Credential | The API key a channel actually uses to call the upstream. Within one channel, your BYOK credentials come before platform credentials | [BYOK fees and credentials](https://platform.lyrouter.com/ai_gateway/docs/byok-cost/en) |
| Virtual model | Bundles a primary model, fallback models, parameters and a system prompt under one name, called as `@vmodel/<name>` | [Virtual models](https://platform.lyrouter.com/ai_gateway/docs/presets/en) |
| Auto smart routing | Called as `lyrouter/auto`; the gateway picks from the enabled models based on how difficult the task is | [Auto routing](https://platform.lyrouter.com/ai_gateway/docs/auto/en) |
| Default Model | A routing setting of the workspace: it takes over when a request has no `model`, or when the requested model fails entirely | [Channels and routing](https://platform.lyrouter.com/ai_gateway/docs/routing/en) |

## Costs and governance

| Concept | Description | Details |
| --- | --- | --- |
| Credits | The platform's billing unit. Platform models deduct Credits by usage, and BYOK calls are charged a service fee per call. The balance is split into a paid balance and a granted balance | [Billing and Credits](https://platform.lyrouter.com/ai_gateway/docs/billing/en) |
| Subscription edition | The Personal edition is free; Team and Enterprise are per-seat subscriptions, and calls are refused once the subscription has expired and its grace period has passed | [Billing and Credits](https://platform.lyrouter.com/ai_gateway/docs/billing/en) |
| Budgets and quotas | API keys can have Token or cost budgets; guardrails can set quotas for members, departments or workspaces. Once a limit is reached, calls return 429 | [Budgets, quotas and rate limits](https://platform.lyrouter.com/ai_gateway/docs/quota/en) |
| Guardrails | Policies that apply to members, departments, API keys or workspaces, including model access control, client access control and content safety detection | [Guardrails and semantic auditing](https://platform.lyrouter.com/ai_gateway/docs/guardrails/en) |
| Request logs | One record per call; the Request ID at the top of the log details is the number to quote when you troubleshoot or report a problem | [Troubleshooting with logs](https://platform.lyrouter.com/ai_gateway/docs/logs/en) |

## How a request is processed

A call goes through roughly the following steps in the gateway. If any step rejects it, an error is returned immediately:

1. **Identify the caller**: the gateway uses the API key to find its workspace and account. An invalid key returns 401; a key that has expired, a source IP that is not on the allowlist, or an account subscription that has expired is rejected at this step.
2. **Security and limit checks**: the guardrail policies (client access control and content safety detection) and quotas in effect for the workspace are applied. A matching blocking policy returns 403, and a used-up quota returns 429.
3. **Determine the model**: `@vmodel/<name>` expands into the virtual model's list of models, `lyrouter/auto` picks a model based on task difficulty, and the Default Model is used when `model` is missing.
4. **Choose a channel and credential**: channels are sorted by the workspace's multi-channel routing strategy and BYOK preferences and tried in order. Before each attempt the gateway checks the Credits balance (an insufficient balance returns 402) and checks the guardrail model access policy against the model actually selected (a blocked model returns 403); when the current channel fails, the next one takes over automatically.
5. **Call the upstream and return the result**: the request is converted to the protocol the upstream needs and sent, and the result is returned in the protocol you called with. Streaming output is supported.
6. **Bill and record**: Credits are deducted by the model actually called and its usage, and a request log is written. Logs are usually searchable within a few seconds after the call ends.

For the exact error messages of each step and how to handle them, see [Errors and request identifiers](https://platform.lyrouter.com/ai_gateway/docs/errors/en); for how the gateway switches channels on failure, see [Retries and fallback](https://platform.lyrouter.com/ai_gateway/docs/fallback/en).