Admin API

Overview

All admin API endpoints are mounted under /admin/api/v1. Authentication uses the AURORA_MASTER_KEY bearer token.

curl -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  http://your-aurora-host/admin/api/v1/usage/summary

The dashboard UI at /admin/dashboard is a separate interface � see Admin Dashboard.

Configuration

Authenticate every request with Authorization: Bearer $AURORA_MASTER_KEY (or a managed key with the appropriate scope). The full request/response body for every endpoint is generated from the Go source into apps/aurora/docs/docs.go and served at /swagger/index.html when SWAGGER_ENABLED=true and DEBUG=true.

Dashboard

OSS.

Usage

OSS.

GET /admin/api/v1/usage/summary

Response:

{
  "total_requests": 1542,
  "total_input_tokens": 2450000,
  "total_output_tokens": 890000,
  "total_tokens": 3340000
}

GET /admin/api/v1/usage/daily

Cache

OSS.

POST /admin/api/v1/cache/debug

Request:

{
  "method": "POST",
  "path": "/v1/chat/completions",
  "headers": {
    "Authorization": "Bearer sk-aurora-..."
  },
  "body": {
    "model": "openai-primary/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }
}

method defaults to POST; path defaults to /v1/chat/completions. The endpoint only works when the response cache is enabled; otherwise it returns feature_unavailable.

Response (real shape from internal/response_cache/middleware.go:49):

{
  "path": "/v1/chat/completions",
  "cache_type": "exact",
  "exact_cache_key": "aurora:response:sha256:...",
  "semantic_params_hash": "",
  "semantic_cache_key": "",
  "semantic_threshold": 0.0,
  "prompt_similarity_threshold": 0.0,
  "exact_ttl_seconds": 3600,
  "semantic_ttl_seconds": 0,
  "streaming": false,
  "cacheable": true,
  "miss_reason": "",
  "guardrails_hash": "sha256:...",
  "embedder_identity": "openai/text-embedding-3-small",
  "effective_content_type": "application/json"
}

Use this to explain "why did this prompt miss the cache" without sending the real request.

Audit & Console

OSS (requires LOGGING_ENABLED=true for audit, no flag for console).

Providers & Pools

OSS.

POST /admin/api/v1/providers

Request:

{
  "name": "openai-primary",
  "type": "openai",
  "api_key": "sk-...",
  "base_url": "",
  "api_version": "",
  "models": ""
}

Models

OSS.

The admin models response includes provider_type and provider_name for each model, unlike the public /v1/models.

Model Access Overrides

OSS.

The selector is provider/model URL-encoded. For example, openai-primary%2Fgpt-4o-mini.

PUT /admin/api/v1/model-overrides/

Request:

{
  "enabled": true,
  "user_paths": ["/team/alpha"],
  "metadata": {
    "display_name": "GPT-4o mini (team alpha only)",
    "context_window": 128000,
    "max_output_tokens": 16384,
    "capabilities": {"tools": true}
  }
}

Model Pricing

OSS.

Aliases

OSS.

PUT /admin/api/v1/aliases/

{
  "name": "fast-default",
  "target": "openai-primary/gpt-4o-mini",
  "description": "Cheap default for the team"
}

Combos

OSS.

Guardrails

OSS.

See Guardrails for the body shape of each guardrail type.

Workflows

OSS.

See Workflows for the body shape.

Managed API Keys

OSS.

POST /admin/api/v1/auth-keys

{
  "name": "team-alpha-service",
  "description": "Backend service key",
  "user_path": "/team/alpha/service",
  "tenant_id": "",
  "allowed_providers": ["openai-primary"],
  "allowed_models": ["openai-primary/gpt-4o-mini"],
  "denied_models": [],
  "provider_pool_id": "",
  "rate_limits": {
    "requests_per_minute": 60
  },
  "expiry": "2026-12-31T00:00:00Z"
}

Response (raw key is shown once):

{
  "id": "key-abc123",
  "name": "team-alpha-service",
  "key": "ak_live_��������������",
  "created_at": "2026-07-14T12:00:00Z",
  "expires_at": "2026-12-31T00:00:00Z"
}

The tenant_id field is accepted in OSS but only enforced in Enterprise (where tenant isolation is real). In OSS, use user_path and routing scopes to achieve the same effect.

CLI Tools

OSS. The CLI Tools feature generates config snippets and optionally writes them to the user's home directory for 14 supported coding agents and CLI tools. See CLI Tools for the full feature.

The apply endpoint is gated by CLI_TOOLS_APPLY_ENABLED=true. With it off (the default in oss.example.yaml), /apply returns 403 and only /preview is usable.

Budgets

Available with Enterprise advancedBudgets capability. OSS returns 403 edition_restricted.

Tenants

Available with Enterprise identity capability. OSS returns 403 edition_restricted.

Authentication & Session

Available with Enterprise identity capability. Login/OIDC endpoints are unauthenticated in Enterprise.

In OSS, GET /admin/api/v1/auth/me is the only auth endpoint that returns a real response. It returns 503 if identity is not configured (i.e. always in OSS), 401 for an unauthenticated request to a configured identity system, and 200 for an authenticated one.

Identity Users

Available with Enterprise identity capability.

Identity Roles

Available with Enterprise identity capability.

Other Routes

OSS.