Core Concepts

If you are new to Aurora, you can get a long way on four ideas: providers, models, aliases, and workflows. Two more — pools and combos — show up once you scale beyond a single upstream. This page explains each in plain language with a small example and the dashboard location to configure it.

Providers

A provider is a connection to one upstream AI service. Aurora auto-discovers providers from environment variables — set OPENAI_API_KEY and Aurora creates an openai provider with its default model list; set ANTHROPIC_API_KEY and an anthropic provider appears. You can also define providers in config.yaml or via the admin API.

The same provider type can have multiple instances by suffixing the env var name with a label:

OPENAI_EAST_API_KEY=sk-...     # provider: openai-east
OPENAI_WEST_API_KEY=sk-...     # provider: openai-west

Underscores become hyphens in the provider name. The full matrix of supported providers is in Providers Overview.

Models

A model is a specific model ID on a specific provider. The full ID you send to Aurora is provider/model — for example, openai-primary/gpt-4o-mini or anthropic/claude-sonnet-4-5.

Aurora gets its model catalog three ways:

1. Auto-discovery — Aurora calls the provider's /models endpoint on startup.
2. Configured lists — <PROVIDER>_MODELS=id1,id2,id3 overrides the auto-discovered list. Set CONFIGURED_PROVIDER_MODELS_MODE=allowlist to expose only configured models for that provider.
3. Manual additions — add models through the dashboard or admin API when discovery does not surface what you need.

You can hide the full provider catalog and expose only your chosen model names — see Model Management.

Aliases

An alias is a stable model name that your app uses, decoupled from the real upstream model. Aliases are the primary way to rename, redirect, and version-control the models you offer.

regular  -> openai-primary/gpt-4o-mini
smarter  -> anthropic/claude-sonnet-4-5
fastest  -> groq/llama-3.1-8b-instant

Your app sends "model": "regular" and Aurora resolves it to openai-primary/gpt-4o-mini before contacting the provider. To change which model backs the alias, edit the alias in the dashboard — no app change required. See Aliases and Model Management.

Pools

A pool is a named group of compatible provider instances that Aurora dispatches across using health, latency, and load. Use pools for higher availability, traffic spreading, or regional routing.

{
  "model": "jina-pool/jina-embeddings-v3",
  "input": ["Hello from Aurora."]
}

Aurora picks a member of jina-pool on each call. Pools can use round_robin or weighted strategies and skip unhealthy members. See Provider Pools.

Combos

A combo is a multi-model orchestration: Aurora calls several models on one request and returns a combined result. The classic use is a cheap model for drafting and an expensive model for review, or a small model for routing and a large model for the answer.

{
  "model": "router-then-expert",
  "messages": [{"role": "user", "content": "..."}]
}

Combos are defined in the dashboard or admin API. See Combos for a worked example.

Model overrides (access rules)

A model override is a per-(provider, model) rule that enables, disables, or scopes access. Rules can target one model, one provider, or the whole catalog, and can be further restricted to a user_path subtree.

# Example: only the /team/alpha subtree can use gpt-4o
overrides:
  - match: openai-primary/gpt-4o
    enabled: true
    user_paths: ["/team/alpha"]

Overrides also control metadata: display name, context window, capabilities, and pricing. See Model Management.

Workflows

A workflow is a per-(provider, model, user_path) policy that turns features on or off. Workflows are how you say "for the support team, use the cache and audit log, but skip guardrails". Aurora applies the most specific matching workflow on each request.

workflows:
  - match:
      provider: openai-primary
      model: gpt-4o-mini
    cache: { enabled: true }
    audit: { enabled: true }
    guardrails: { enabled: false }

Workflows are first-class in the dashboard and admin API. They are the recommended way to operate Aurora in production — see Workflows.

Routing scopes (user paths)

A user path is an opaque hierarchical string that callers attach to a request to identify themselves — a team, service, customer, or tenant. Aurora uses it for overrides, workflows, budgets, and analytics.

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-aurora-..." \
  -H "X-User-Path: /team/alpha" \
  -d '{"model": "gpt-4o-mini", "messages": []}'

In Enterprise, user paths become tenants and get budgets and RBAC. In OSS they are advisory and power overrides/workflows. See Routing Scopes and User Path.

Managed API keys

A managed API key is a gateway-issued key (separate from your upstream provider keys) that you can scope to specific providers/models, rate-limit, and revoke without rotating upstream credentials. Your team uses the managed key against http://your-aurora-host/v1; Aurora holds the real provider keys and enforces the policy.

See Managed API Keys for the create-key flow.

Caches

Aurora has three distinct caches. They sound similar; they are not.

See Cache and Prompt Cache.

Guardrails

A guardrail is a content-safety transform that runs on requests, responses, or both. Aurora ships with:

• System prompt injection / override / decoration
• Regex blocking and sanitization
• PII redaction (email, phone, SSN, credit card)
• Length limits (characters and estimated tokens)
• LLM-based content altering (Enterprise)

See Guardrails.

Putting it all together

A typical request flow:

1. App calls http://aurora/v1/chat/completions with a managed key, an alias name, and a user_path header.
2. Aurora resolves the alias to a real (provider, model), applies the matching workflow and override, and checks the matching managed-key policy.
3. Aurora looks up an exact cache entry, then a semantic cache entry, and returns a hit if either matches.
4. Otherwise, Aurora dispatches to the provider (or pool), capturing audit log + usage + optional guardrail transforms along the way.
5. The response is streamed back to the app; Prometheus counters and the dashboard update on the next flush interval.

The Quick Start walks you through steps 1 and 2. The remaining pages in the OSS tab walk you through 3, 4, and 5.