Identity guide
How to configure caller identities for LLM and MCP traffic.
Overview
Cortega uses identities to decide who is calling, which team owns the traffic, and which policies apply.
Pass-through LLM traffic is different: clients use their own upstream provider credentials, so Cortega does not create a virtual-key identity for those calls. Keyless pass-through LLM traffic falls to the Default team. See Pass-through routing.
There are two common identity paths:
| Surface | What authenticates the caller | What Cortega uses it for |
|---|---|---|
| LLM | Cortega-generated key, or another configured LLM auth provider | Team budgets, routing, guardrails, and observability |
| MCP | MCP auth provider plus identity matching | Team assignment, MCP server/tool authorization, guardrails, and observability |
LLM key identities
Navigate to Identities.
Use a Cortega key identity when developers, apps, or agents need to call the LLM gateway.
- Create or select a Cortega key identity.
- Assign it to a team.
- Add optional metadata such as user, agent, service account, project, or cost center.
- Save the identity.
- Give the raw
ck_...key to the caller only once.
The raw key is shown once. After that, Cortega stores only a hash and safe display metadata.
MCP auth providers
Use MCP auth providers to tell Cortega how MCP callers prove who they are.
Supported methods:
| Method | Use when |
|---|---|
| MCP OAuth/JWT | MCP clients obtain bearer tokens from your IdP |
| Generic JWT | Callers already have a standard JWT bearer token |
| API key | You want a simple key-based MCP caller |
| Basic Auth | You need username/password-style MCP access |
| OIDC | Browser-oriented identity is needed |
For JWT-shaped methods, configure claim names for subject, role, and
tenant. The defaults are sub, roles, and tenant.
Required fields:
| Method | Required | Optional |
|---|---|---|
| MCP OAuth/JWT | Name, MCP surface, issuer, JWKS URL, protected-resource URL, at least one claim-to-team rule | Audiences, scopes, provider kind, introspection |
| Generic JWT | Name, LLM and/or MCP surface, issuer, JWKS URL, at least one claim-to-team rule | Audiences, introspection |
JWKS URL (MCP OAuth/JWT and Generic JWT) must be a URL that already
serves a JWKS JSON document ({"keys":[...]}), typically
https://<issuer>/.well-known/jwks.json or a Keycloak
/protocol/openid-connect/certs URL. Cortega fetches that URL when you
save. A homepage, 404, or HTML page is rejected, so Cortega is never
given a JWKS URL it cannot load.
Generic JWT and API key identities can be enabled together on the same
surface: Cortega accepts a validated JWT or a known key on the shared
Authorization: Bearer header. MCP OAuth/JWT (the OAuth discovery
flow) is the exception: it can't share the header with API keys, so
enabling it on MCP still requires disabling MCP key identities. Use
Generic JWT instead if you need both. On a multi-tenant install, MCP
OAuth/JWT is unavailable altogether; use Generic JWT.
Basic Auth may still combine with JWT (it uses the Basic scheme).
Cortega only accepts one Basic Auth policy per listener, so it allows at
most one Basic Auth identity on LLM and one on MCP; extra users belong in
username-to-team rows on that provider. While MCP OAuth/JWT is
enabled, the MCP Playground rejects Playground Key and pasted keys; paste
a JWT instead.
Two tenants can each configure their own Generic JWT identity. If they use different IdP issuers it just works; if they share an issuer (both on Google, say), each must set a distinct Audience so Cortega can tell their tokens apart.
If the MCP Playground returns JWT token required, Cortega did not
accept a valid JWT. Paste the raw token, not Bearer …. The token iss
must match Issuer, aud must match Audiences (or the protected-resource
URL when Audiences is blank), and the token must verify against the JWKS
URL. Re-save the MCP OAuth/JWT identity or restart management-backend so
Cortega picks up audience defaults.
MCP team resolution
MCP authorization is granted per Cortega team. MCP auth providers authenticate the caller and expose a trusted team value, such as API key metadata, a JWT/OIDC tenant claim, or a Basic Auth username-to-team mapping stored on the auth provider. The MCP Authorization table then grants that team access to servers and tools.
Example:
| Field | Value |
|---|---|
API key metadata team | Default |
JWT/OIDC claim_teams tenant=Default | team Default |
Basic Auth user_teams username alice | team Default |
Each team should have at most one MCP Authorization row.
Sorting and review
The Identities table is sorted alphabetically by name. Check:
- Surface: LLM, MCP, or both.
- Auth method.
- Team.
- Enabled state.
Disable identities that should not resolve traffic, rather than deleting them immediately, if you want an audit-friendly rollback path.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| LLM call is attributed to the wrong team | Key metadata or team assignment is wrong | Open the identity and verify its team |
| MCP call says no identity matches | The trusted team from the credential has no enabled MCP authorization | Check API key metadata, JWT/OIDC claim_teams, or Basic Auth username-to-team mapping, then MCP Authorization |
| JWT authenticates but LLM uses the Default router | Token verified, but no claim_teams row matched | Add claim=value to team on the Identities JWT/OIDC provider; do not rely on MCP Authorization grants |
| MCP call authenticates but cannot call a tool | Identity resolved, but MCP Authorization does not grant that server/tool | Open MCP Authorization |
| MCP Playground only sees the Default team's tools | The shared Playground MCP key is created on the Default team | Set that key's team (MCP > Identities, "[Playground] MCP Shared") to the team you want to test; the Playground keeps your choice from then on |
| Basic Auth identity does not match | Username/password authentication failed, or user_teams does not include that username | Confirm htpasswd and the username to team row on the Identities Basic Auth provider |