Model Management

Overview

Aurora separates the model name your app sends from the provider model Aurora uses upstream. This gives operators one place to manage aliases, model access, configured provider inventories, pricing metadata, and model visibility.

Use the admin dashboard at Models for the interactive flow.

Aliases

An alias is a stable model name that points to a concrete provider model. Your app sends the alias in the model field, and Aurora resolves it before sending the request upstream.

For example, after you confirm the real upstream model IDs from GET /admin/api/v1/models, you can create aliases such as:

regular -> <provider-name>/<standard-model-id>
smarter -> <provider-name>/<larger-model-id>
 

Your app can then send:

{
  "model": "regular",
  "messages": []
}
 

Shadow models

An alias can use the same name as an existing model. This lets you redirect an existing application model string without changing application code.

For example, if an app already sends a provider model ID, create an alias with that same name and point it to another real selector from the admin model list. The app keeps sending the old model string; Aurora resolves the alias before the upstream request is made.

Expose only aliases

To hide provider model inventories from GET /v1/models, set:

KEEP_ONLY_ALIASES_AT_MODELS_ENDPOINT=true
 

When enabled, Aurora returns enabled aliases from /v1/models instead of the full upstream model list.

Model access rules

Model access overrides can limit which callers see or use a provider, model, or alias. Rules can target:

• / for all providers and models
• {provider_name}/ for one configured provider
• {provider_name}/{model} for one model on one provider
• a model ID without a provider name

Attach user_paths to a rule to scope access to a team, service, customer, or tenant subtree.

Configured model lists

Every provider supports configured model lists with <PROVIDER>_MODELS, such as:

OPENROUTER_MODELS=openai/gpt-oss-120b,anthropic/claude-sonnet-4
ORACLE_MODELS=openai.gpt-oss-120b,xai.grok-3
 

By default, CONFIGURED_PROVIDER_MODELS_MODE=fallback uses configured lists only when upstream /models is unavailable or empty. Set CONFIGURED_PROVIDER_MODELS_MODE=allowlist to expose only configured models for providers that define a list.

Pricing metadata

Aurora can track model pricing metadata for usage analytics and cost reports. Keep pricing current when you add aliases or provider-specific model IDs so dashboard cost analytics stay meaningful.

Manual management

Use the dashboard at Models to inspect inventory, create aliases, edit access overrides, and update pricing overrides. For static inventory hints, configure provider model lists in YAML or environment variables:

providers:
  local-vllm:
    type: vllm
    base_url: "http://localhost:8000/v1"
    models:
      - id: my-local-chat-model
        metadata:
          display_name: "My local chat model"
          context_window: 32768
          max_output_tokens: 4096
          modes: ["chat"]
          capabilities:
            tools: true
          pricing:
            currency: USD
            input_per_mtok: 0
            output_per_mtok: 0
 

Set CONFIGURED_PROVIDER_MODELS_MODE=allowlist when you want Aurora to expose only configured models for providers that define a model list. Leave the default fallback mode when you want Aurora to prefer upstream /models and use the configured list only if upstream discovery is unavailable.

Server API automation

For endpoint reference see the Admin API section.

Access override example:

curl -X PUT "http://your-aurora-host/admin/api/v1/model-overrides/openai-primary%2Fmy-model" \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "user_paths": ["/team/alpha"]
  }'
 

2-minute walkthrough: create your first alias

By the time you get here you have sent one or more requests through Aurora and have a list of real provider/model IDs in /v1/models. The fastest way to stabilize those names for your app is to create an alias.

# 1. Confirm the real upstream ID
curl -s http://localhost:8080/v1/models \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" | jq '.data[] | select(.id | contains("gpt-4o-mini"))'
 
# 2. Create the alias
curl -X POST http://localhost:8080/admin/api/v1/aliases \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fast-default",
    "target": "openai-primary/gpt-4o-mini",
    "description": "Cheap default for the team"
  }'
 
# 3. Use the alias as if it were a real model
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -d '{
    "model": "fast-default",
    "messages": [{"role": "user", "content": "Hello from Aurora"}]
  }'

To redirect fast-default to a different model later, change the alias � no app change required:

curl -X PUT http://localhost:8080/admin/api/v1/aliases/fast-default \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fast-default",
    "target": "groq/llama-3.1-8b-instant"
  }'

The next request with model: "fast-default" goes to Groq, not OpenAI. Your app and your teammates' apps need no change.

Shadow models (redirect an existing model name)

If your app already sends a specific provider model ID � say it was hard-coded to openai/gpt-4o-mini before Aurora existed � create an alias with that exact name and point it elsewhere:

curl -X POST http://localhost:8080/admin/api/v1/aliases \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai/gpt-4o-mini",
    "target": "openai-primary/gpt-4o-mini"
  }'

The app keeps sending openai/gpt-4o-mini; Aurora resolves the alias to your actual deployment openai-primary/gpt-4o-mini before the upstream call. Use this to migrate existing clients onto Aurora without touching their code.

Lock down a model to a team

To make sure only one team's traffic reaches an expensive model:

# Disable the model globally, then enable it for /team/alpha only
curl -X PUT "http://localhost:8080/admin/api/v1/model-overrides/openai-primary%2Fgpt-4o" \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "user_paths": ["/team/alpha"]
  }'

Requests without X-User-Path: /team/alpha get a 403; requests with it pass through.

Hide the upstream catalog

Once you have aliases you control, hide the raw provider model list from /v1/models so your app only sees your stable names:

KEEP_ONLY_ALIASES_AT_MODELS_ENDPOINT=true

Restart Aurora. /v1/models now returns only enabled aliases. Re-enable upstream discovery by flipping the flag and restarting.