User guide

Step-by-step guide for platform administrators to configure Cortega from zero to governed LLM traffic.

Overview

Cortega is an AI Governance & Intelligence Platform that sits between your organization's AI consumers (developers, agents, tools) and upstream LLM providers (OpenAI, Anthropic, and others). It routes every request through a managed fleet of Cortega gateway proxies, enforcing:

Feature	What it does
Virtual keys	Authenticate callers without exposing real provider credentials
Provider management	Store provider API keys encrypted at rest; inject them server-side
Model routing	Control which model maps to which provider (or multiple providers)
Team budgets	Cap spending per team; block over-budget keys automatically
Provider budgets	Cap spending per provider (for example, limit your OpenAI monthly spend)
Team routing preferences	Give each team weighted or failover routing across models
Audit logging	Every config change is tamper-evident and hash-chained
Observability	Per-request telemetry: latency, tokens, cost, model, team, key

Single-tenant vs. multi-tenant installs

Most installs run as a single tenant and every administrator sees everything in this guide. A multi-tenant install has a System tenant (Tenant 0) whose operators own the shared infrastructure (gateways, providers, the license, platform health, and the list of tenants) and any number of ordinary tenants, each with its own administrators, teams, keys, budgets, guardrails, and traffic. A per-tenant administrator does not see the platform-scoped screens (Gateways, Providers, License, Platform Health, Tenants) and only ever sees their own tenant's data. Tenant setup and roles are covered in the User management guide.

1. Logging in for the first time

Cortega seeds a default admin account when first deployed.

Field	Value
URL	your production URL
Email	[email protected] (defined in installation scripts)
Password	defined in installation scripts

After first login, immediately change the admin password and configure SSO if available.

The Cortega sidebar is organized into product groups. Each group starts with a Getting Started page and ends with Tips and FAQ. Which groups and items you see depends on your license, your role, and (on a multi-tenant install) your tenant.

AI Border Gateway, the LLM/MCP governance gateway:

• Getting Started: guided setup and a "Needs attention" panel for configuration problems
• Observability: raw LLM/MCP traffic query tables and live logs
• Insights: team spend, model/gateway performance, security findings, recommendations, and workload analysis
• Models: providers, concrete models, provider budgets, and the platform Routing Policy tab
• MCP Servers: register MCP tool servers and discover tools
• Identities: LLM key identities and inbound LLM/MCP auth providers
• Teams: team registry and team budgets
• Model Authorization: team-level model routing preferences
• MCP Authorization: grant teams access to MCP servers and tools
• A2A: register AI agents (principals on the data plane)
• Guardrails: LLM/MCP request and response policies
• Rate Tables: the cost catalog
• Applications: register Agentic Applications for per-app analytics
• Gateways: view and manage gateway instances (platform operators only)
• Console: Client Setup, Model Playground, and MCP Playground

Endpoint Guard: the native agent that governs AI traffic on desktops and browsers. See Endpoint Guard.

Cortega Agents: background analysis of governed responses (fact-checking, scoring, sentiment, compliance, and more). See Cortega Agents.

AI Bench: LLM safety/quality benchmark suites.

System: Users & Access, API Access, Tenants, Audit Log, License, and Platform Health. The last three, plus Gateways and Providers, are platform-scoped: on a multi-tenant install they are visible only to operators in the System tenant (Tenant 0), not to per-tenant administrators.

Related setup guides

Use these focused guides for the newer governance surfaces:

• Identity guide
• MCP servers guide
• MCP authorization guide
• Pass-through routing
• Guardrails guide
• Client identification guide

Provider interworking, Agentic Applications, and load balancer setup have their own guides too, shipped with your install package.

2. Understanding the setup order

Start at Getting Started. The AI Border Gateway → Getting Started page runs a set of configuration-health checks and shows a "Needs attention" panel listing anything that is misconfigured or incomplete: a provider whose diagnostic failed, a model with no cost data, a team routed to a disabled model, an undelivered gateway config, and so on. The same problems also show as a warning badge on the affected row in Models and MCP Servers. If the install has unresolved errors, Cortega lands you here after login instead of the dashboard. Work the list top to bottom.

Configuration in Cortega flows top to bottom. You must create resources in this order because each step depends on the previous one: Providers, then Models, then Teams, then Budgets, then Virtual Keys, with Model Authorization and named virtual models as optional steps after Teams.

• Providers hold the actual API keys to LLM services (OpenAI, Anthropic, and others).
• Models are concrete model IDs (like gpt-4o or claude-sonnet-4-6) attached to a provider.
• Teams group virtual keys together for budget tracking. Every key belongs to a team.
• Budgets (team and provider) cap monthly spending.
• Virtual keys are what developers and agents use to call the gateway.
• Model Authorization defines how models are selected per team.

3. Adding providers (API credentials)

Navigate to Models → Providers.

A provider represents an upstream LLM service. You must add at least one provider before anything else.

1. Click Add provider.
2. Fill in the form: a friendly provider name, the provider type (OpenAI, Anthropic, Gemini, Bedrock, Azure, Custom, and others), and the credential source.

Credential source options:

Source	When to use
API key	Paste the key directly into Cortega's UI. It's AES-256-GCM encrypted at rest and never returned in API responses. The simplest option.
Environment variable	Cortega reads the key from an environment variable on the gateway container, not from its control plane database. Enter the variable name in the UI (for example OPENAI_API_KEY); put the value in .env.provider-keys.
AWS IAM / runtime credentials	For Amazon Bedrock, use Cortega's ambient AWS credential chain: an instance role, task role, IRSA, or exported AWS environment variables.
AWS access key / secret	For Amazon Bedrock, store an AWS access key ID, secret access key, and optional session token in Cortega.
Client-supplied upstream credential	Cortega stores no upstream key. Each caller sends its own provider key in a separate request header; Cortega rewrites it to the provider-native header and strips it before dispatch. Not supported for Bedrock, Vertex, Azure, or Copilot. See Pass-through routing.
No explicit credential	Cortega sends no configured provider credential. Available for Custom and Ollama providers where the upstream endpoint may be local or unauthenticated.

Expand Advanced endpoint override if you need a custom base URL (for example, self-hosted models, Azure, AWS Bedrock region), then click Add provider.

The provider appears in the table with status active. For API-key providers, provider keys never leave the server-side path; they're injected by Cortega at request time, never exposed to clients. For passthrough providers, the upstream sees the validated credential from the incoming request.

If you leave Base URL empty, Cortega uses the provider's default endpoint (for example https://api.openai.com/v1 for OpenAI). Bedrock and Vertex AI also need a region field.

4. Configuring models

Navigate to Models → Models.

A model is a concrete model identifier (like gpt-4o or claude-sonnet-4-6) tied to a provider.

1. Click Add model.
2. Select a provider; the model catalog for that provider type is shown.
3. Select a model from the catalog, or choose Other / custom model and type the model ID manually.
4. Expand Advanced routing if you want the outgoing model name to differ from the incoming model name (for example, a client requests gpt-4 but you forward to gpt-4o-mini).
5. Click Add model.

A model is either Active (available for routing) or Disabled (ignored by Cortega, receives no traffic). Disable a model instead of deleting it if you want to temporarily remove it from the routing pool.

The Outgoing model setting remaps model names transparently: same as incoming (unchanged), a different catalog model (remapped server-side), or a custom provider-specific name.

When an admin refreshes rate tables, Cortega imports pricing from models.dev. For Amazon Bedrock, the management backend also tries to call bedrock:ListInferenceProfiles; if allowed, Cortega replaces Bedrock base model IDs that aren't valid for on-demand invocation with runnable inference profile IDs. This cleanup is fail-open: if the permission is unavailable, the rate-table refresh still completes and the Bedrock cleanup is skipped.

5. Creating teams and setting team budgets

Navigate to Teams → Teams.

Teams group virtual keys for spend tracking and budget enforcement. Every virtual key must belong to a team. Cortega always has a Default team; keys not explicitly assigned to another team go here, and the Default team can't be deleted.

To create a team: click Add Team, enter a team name (immutable after creation), set the monthly budget (Unlimited, or a USD amount), and click Add team.

Team budget columns: Monthly budget (the USD cap), Spend (MTD, dollars spent month-to-date), Available (budget minus spend), Keys (how many virtual keys are assigned), and Status (Within budget, Unlimited, or Blocked over budget).

When a team exceeds its budget, its status changes to Blocked, and every virtual key belonging to it is blocked: requests using those keys get a 402 or 429 response. The block lifts on the 1st of the next month when spend resets, or immediately if an admin increases the budget.

Deleting a team reassigns all its virtual keys to the Default team.

6. Setting provider budgets

Navigate to Models → Provider budgets.

Provider budgets cap spending per provider regardless of which team is calling, useful for limiting your total OpenAI bill, preventing accidental spend spikes, or enforcing a hard cap on third-party API costs.

A toggle at the top controls the default: Allowed means providers without an explicit budget are unlimited; Disabled means they default to $0 and are completely disabled until given a budget. Set a per-provider budget by entering a dollar amount and clicking Save; click Use default to revert to the global default.

When both a team budget and a provider budget exist, both are enforced independently: a request passes only if the team has remaining budget and the provider has remaining budget.

7. Optional: named virtual models (API)

Named virtual models (/api/v1/llm-virtual-models) are customer-facing model names that route across one or more concrete provider models (failover, weighted, or conditional). They're configured through the management API, not the console. For team-level weighted splits and failover in the console, use Model Authorization instead; Cortega compiles each team router into a managed virtual model automatically.

8. Model Authorization

Navigate to Model Authorization, in the AI Border Gateway group.

Model Authorization is optional. When a team's virtual key matches a team router, Cortega rewrites that request to the team's managed router model before it reaches the upstream provider. Teams without a router keep using the requested model normally.

Team routing preferences support two strategies: weighted split sends traffic across selected models by exact percentage weights (must add to 100), and failover priority tries lower priority values first, retrying the next priority on the same request when a preferred target is unreachable or returns a retryable error.

Whether an unhealthy model is taken out of rotation, and for how long, and whether a failed request is retried, is configured once for the whole platform on the Routing Policy tab, not per team.

To set up team routing: click Add Model Authorization, select a team, choose Weighted split or Failover priority, add models, enter weights (for weighted) or priorities (for failover), and click Save router.

Routing Policy

Navigate to Models → Routing Policy (platform administrators only). Two independently toggleable sections apply to every gateway:

• Model health/eviction: when to treat an upstream model as unhealthy (HTTP 5xx, connection failures, and/or HTTP 429), how many consecutive failures to allow first, and how long an evicted model stays out of rotation, either from the provider's rate-limit response headers or a fixed duration that grows on each repeated eviction and resets after a success. Individual models can override this on their edit form.
• Same-request retry/failover: how many times a failed request is retried, how long to wait between retries, and which status codes trigger a retry. A retry re-enters the team's router; it only lands on a different model if the first one was evicted.

If retry is on while health/eviction is off, a warning is shown: retries may go back to the same failed model because unhealthy models are never evicted.

9. Creating LLM key identities

Navigate to Identities.

LLM identities are how developers, agents, and tools authenticate to the Cortega gateway. Each LLM identity is backed by a ck_-prefixed Cortega key that replaces real provider API keys and resolves to a team plus metadata.

To create one: click New Identity, enter a name, choose a team, optionally set an expiry and metadata, then click Create Identity. The raw identity key is shown exactly once; copy it immediately. Cortega stores only a salted SHA-256 hash and cannot recover the raw key.

Built-in metadata fields include Team, User, Agent, and Service Account. Custom fields can be created for any purpose and are available for conditional routing and appear in telemetry. For MCP auth providers and MCP caller matching, see the Identity guide.

Managing keys: Rotate generates a new key (the old one stops working); Expire sets an immediate expiry; Revoke immediately and irreversibly disables the key; Purge permanently deletes the record; the team dropdown in the key list reassigns teams.

10. Connecting clients (developers)

Navigate to Console → Client Setup.

The Console page provides ready-to-copy code snippets for connecting to Cortega from various tools and SDKs: Python and TypeScript SDKs (OpenAI and Anthropic), Claude Code CLI, Codex CLI, and OpenCode.

From the developer's perspective: an admin issues them a virtual key (ck_...), they point their SDK's base_url to the Cortega gateway endpoint shown in Client Setup, they use the virtual key as the API key, and they request models by name as usual. The gateway authenticates the key, enforces budgets and policies, injects the real provider key, and forwards the request. The developer sees the response just like a direct provider call.

Copy the exact LLM Gateway URL from the Client Setup page rather than assuming a fixed hostname; it differs per install. When a load balancer fronts the gateway fleet, Client Setup shows one load-balancer URL per surface (LLM / MCP / HTTP); send all client traffic there. Platform- operator admins (Tenant 0) additionally see a "Where the client runs" toggle and internal VPC addresses, choosing the internal URL for same- network clients and the external/load-balancer URL otherwise. Tenant users only ever see the external address.

# For Anthropic-compatible tools (Claude Code, etc.)
export ANTHROPIC_BASE_URL="<LLM endpoint from Client Setup>"
export ANTHROPIC_API_KEY="ck_your_virtual_key"

# For OpenAI-compatible tools (Codex, OpenCode, etc.)
export OPENAI_BASE_URL="<LLM endpoint from Client Setup>/v1"
export OPENAI_API_KEY="ck_your_virtual_key"

OpenAI-compatible clients may use either /v1/chat/completions or /v1/responses. When the requested model routes to an Anthropic provider, use Chat Completions or the Anthropic-compatible /v1/messages endpoint, not /v1/responses.

The Console also has a Model Playground and an MCP Playground. Both send a real governed request through the gateway from the browser (the browser never talks to a gateway directly; the management backend originates the call). Pick the caller identity to test as, choose a model or MCP server, and send, to confirm a provider, model route, guardrail, or MCP tool grant behaves as configured before handing a key to a developer.

11. What happens after a call is made

When a developer sends an LLM request through Cortega:

1. Virtual key authentication. The gateway hashes the key (SHA-256) and looks it up. Not found or revoked returns 401. Team over budget returns 402/429. If the key passes, the Authorization header is stripped before the upstream call.
2. Model resolution. A virtual model name resolves through its failover or conditional strategy; a concrete model resolves to its provider, possibly rewritten by a team routing preference.
3. Outgoing model name override, if configured.
4. Provider dispatch, using whichever credential mode the provider is configured for.
5. Response streaming, recording token counts, latency, model, provider, team, virtual key, cost, and any guardrail findings.
6. Telemetry export, available in Observability's raw query tables and rolled up in Insights.

The developer sees a normal LLM response and is unaware of which provider served it, whether a failover occurred, budget enforcement (unless their team is blocked), or guardrail scanning (unless rejected).

Error scenarios: invalid/missing key returns 401; team or provider over budget returns 402/429; model not found returns 400; no healthy provider returns 502/503; a guardrail rejection returns 400/403.

12. Monitoring and observability

Insights (high-level)

Navigate to Insights.

Tab	What it shows
Team Spend	Per-team request count, token usage, window spend, and month-to-date spend against budget
Model Performance	Per-provider/model request count, error rate, latency, and spend
Gateway Performance	Per-gateway request count, error rate, latency, token usage, spend, and top models served
Security Findings	Guardrail/security findings by severity, type, team, agent, model, MCP server/tool, outcome, and last-seen time
Recommendations	Model-upgrade and model-discovery advice from Model Intelligence, scoped to your own traffic
Workload	A models by workload-category matrix, from the Workload Analyzer agent
Superset Insights	Embedded dashboards for deeper ad hoc analysis

On a multi-tenant install, System-tenant operators get platform-wide dashboards and a tenant selector; per-tenant users get dashboards scoped to their own traffic.

Observability (raw data)

Navigate to Observability. Raw traffic query tables let you filter by virtual key, team, model, provider, time range, or gateway instance. Each row shows Agent Stack (which application made the call), Timestamp Source, request/response tokens, latency, model, provider, and cost. See the Client identification guide for setting X-Cortega-Application from your own apps.

Platform Health

Navigate to Platform Health. Shows the health of Cortega backend services, all gateway instances, core traffic telemetry/cache/database services, and the OTEL collector and Prometheus.

13. Audit logging

Navigate to System → Audit Log (requires the audit permission; the edition must include the audit-log feature).

Every mutating admin action is recorded in a tamper-evident, hash-chained audit log: provider and model changes, team and budget changes, virtual key lifecycle, user lifecycle, guardrail changes, and MCP server/ authorization changes. The Verify Chain button validates the cryptographic integrity of the entire log.

14. Quick-start checklist

• Add at least one provider (Models → Providers → Add provider)
• Configure at least one model (Models → Models → Add model)
• Create at least one team, or use the Default team
• Optionally set budgets
• Issue an LLM key identity, and copy the raw key immediately
• Point a client at the gateway from Console → Client Setup