Managed API Keys

Overview

Managed API keys are gateway-issued credentials for applications, services, teams, tenants, or customers. They let callers use Aurora without receiving upstream provider secrets.

A managed key can carry user_path, allowed providers, allowed models, denied models, a provider pool binding, expiry, and request or token rate limits. In Enterprise profiles, keys can also carry a tenant_id for multi-tenant scoping.

Requests authenticated with a managed key use the key's effective user_path for usage, audit logs, workflows, model access, and routing policy. In Enterprise profiles, the key's tenant_id also scopes these systems.

Manual management

Use the dashboard at Auth Keys to issue keys, review active keys, inspect key usage, and deactivate old keys.

The raw secret value is returned only when the key is created. Store it in your secret manager immediately. Later list endpoints show metadata, not the raw key.

Server API automation

For endpoint reference see the Admin API section.

curl -X POST http://your-aurora-host/admin/api/v1/auth-keys \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "team-alpha-service",
    "description": "Backend service key",
    "tenant_id": "team-alpha",
    "user_path": "/team/alpha/service",
    "allowed_providers": ["openai-primary"],
    "allowed_models": ["<model id returned by /admin/api/v1/models>"],
    "denied_models": [],
    "provider_pool_id": "",
    "rate_limits": {
      "requests_per_minute": 60,
      "tokens_per_day": 1000000
    }
  }'
 

Use managed keys for callers. Keep AURORA_MASTER_KEY restricted to operators and automation that must administer the gateway.

30-second recipe: give a teammate a key

# 1. Create the key
RESP=$(curl -s -X POST http://localhost:8080/admin/api/v1/auth-keys \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "alice-dev",
    "user_path": "/team/alpha/alice",
    "allowed_models": ["openai-primary/gpt-4o-mini"],
    "rate_limits": {"requests_per_minute": 30}
  }')
 
# 2. Pull the key value out
KEY=$(echo "$RESP" | jq -r .key)
echo "Send this to Alice: $KEY"
 
# 3. Alice uses it like any OpenAI key
# curl http://your-aurora-host/v1/chat/completions \
#   -H "Authorization: Bearer $KEY" \
#   -H "Content-Type: application/json" \
#   -d '{"model":"openai-primary/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

Alice's calls show up in the dashboard under Usage filtered by her user_path and key. Revoke the key from the dashboard or DELETE /admin/api/v1/auth-keys/{id} at any time.

How requests get scoped

When a request arrives with a managed key, Aurora attaches the key's metadata to the request context:

• user_path flows into overrides, workflows, and audit/usage logs
• allowed_providers and allowed_models are enforced before the upstream call
• denied_models is checked first (deny wins)
• rate_limits are enforced per key
• provider_pool_id forces the request through a specific pool

If a request would exceed a rate limit, Aurora returns 429 rate_limit_exceeded with X-RateLimit-* headers matching the OpenAI shape.

Rotation and revocation

• Revoke � DELETE /admin/api/v1/auth-keys/{id} immediately invalidates the key. In-flight requests are allowed to complete.
• Rotate � create a new key, deploy the new secret, revoke the old one. There is no built-in expiry; enforce it externally with your secret manager and the expiry field.
• Expire � set expiry: "2026-12-31T00:00:00Z" on key creation. Aurora refuses requests with the key after that timestamp.

Gotchas

• Raw key is shown once � at creation time only. If you lose it, revoke and reissue. There is no "show me the key again" endpoint by design.
• Tenant scoping is Enterprise � tenant_id is honored in Enterprise only. In OSS, set user_path instead and use routing scopes to enforce isolation.
• allowed_models matches the upstream ID � if you also use aliases, allow the alias name, not the resolved upstream name. Aurora resolves aliases first, then enforces the model allowlist.
• Rate limits are per-key, not per-user � if your app shares one key across many end users, the rate limit is the app's, not the user's. Use per-user managed keys if you need per-user limits.
• The dashboard does not show managed-key secrets � only the metadata. Treat the create response as a one-time event and store the secret immediately.

Related

• Admin API: Auth Keys
• Routing Scopes
• User Path
• Enterprise RBAC � key-bound roles in Enterprise