Core concepts

Most setup mistakes come from mixing up provider keys, Lumoswitch access keys, and model names. Understand the call path before configuring production traffic.

Application / agent / developer tool
  -> Lumoswitch base URL + access key
  -> API configuration (client-facing model name + runtime policy)
  -> Model resource
  -> Upstream + credential pool
  -> Model provider

Downstream and upstream

• Downstream is an application calling Lumoswitch, such as the OpenAI SDK, Codex, OpenWebUI, or your own service.
• Upstream is the model service called by the Lumoswitch inference service, such as OpenAI, DeepSeek, Qwen, or local Ollama.
• Model author is the organization that creates a model, such as Anthropic, DeepSeek, or Moonshot AI.
• Inference provider exposes the model API, such as OpenAI API, OpenRouter, or Together AI; one provider can distribute models from many authors.

Downstream clients should only receive Lumoswitch access keys, never provider secrets.

Upstreams and credential pools

An upstream is a configured account and endpoint for one inference provider. It defines the base URL, protocol, and credential pool. Its model list is fetched from the provider, and it may contain multiple encrypted credentials. Different credential priorities compile into ordered fallback tiers. Deployments at the same priority are selected by the current Lumoswitch Runtime policy; Lumoswitch does not promise round-robin behavior.

Model resources

A model resource represents one model supplied by one upstream through one credential source. The same providerModelId from different upstreams is treated as a distinct routable resource.

API configurations

An API configuration is the downstream product boundary. It controls one or more client-facing model names and their targets, candidate resources, routing mode, output protocols, and access-key limits.

Client-facing model name = support-prod
  -> Primary = Qwen / qwen-plus
  -> Fallback = DeepSeek / deepseek-chat

The real model can change while downstream clients continue using support-prod.

Access keys, projects, and apps

Lumoswitch access keys authenticate inference requests through the selected format's standard header: Bearer auth for OpenAI, x-api-key for Anthropic, or x-goog-api-key for Gemini. Full values appear once; Lumoswitch retains only the runtime token identity, prefix, and business state. Each API configuration has a current key; replacement rotation can keep the previous key usable for a short grace period. Projects group configurations into stable product, environment, or customer scopes.

Routing and failover

A decision can depend on configuration mode, aliases, project scope, upstream health, credential priority, and rate limits.