Token Consumers

This is a map of who reads a Corti access token, which part of the token they read, and how — across the whole corticph GitHub estate. It is the consumer-side counterpart to Token Mappers (which client gets which mapper, i.e. how the token is produced) and the Platform Mappers Contract (the claim contract and the target organization model).

Use it for impact analysis: before a claim is renamed, moved, or dropped — and the Organizations migration does all three, moving project identity to organization.<org> and narrowing corti to client-level attributes (see the contract and Organization Migration) — this tells you exactly which repos and which lines break.

1. Two client families, two ways to carry identity

A token's contents depend on which client family minted it. This is the single most important thing to know when reading the tables below — the same consumer behaves differently depending on the token it receives.

Delegated clients most commonly back the Embedded Assistant flow, but that is not their only use — they can equally be configured for direct API access. The token mechanics in the table above apply regardless of which way the delegated client is used.

See Token Mappers for the producer-side mechanics.

2. Master matrix — token field → consumers

Every token field, the repos that read it, and what they do with it.

3. corti.* business-claim consumers

The custom business claims (console_project_id, the billing-provider IDs, is_nfr, retention_minutes, console_distributor_id) are read by four backends — though console_distributor_id has no token consumer today (see the note below). The shared claims struct does not include them, so each consumer defines its own struct. The table also lists Assistant for completeness: it consumes no corti.* claims but is a load-bearing consumer of project identity, deriving consoleProjectId from the groups path on delegated tokens.

4. Signature verification

The token is signed by Keycloak (RS256). Two downstream patterns exist: verify locally against the realm's JWKS, or trust the gateway and parse the payload without verifying.

5. The shared claims structs

There are two shared Go token parsers, and they do not overlap.

corticph/common-service-library package jwtclaims defines the canonical Default struct (golang-jwt v5), used by corti-core-api, call-service, and others. Fields:

Azp, Acr, AllowedOrigins, RealmAccess.Roles, ResourceAccess, Scope, Sid, Email, EmailVerified, PreferredUsername, GivenName, FamilyName, Realm — plus the embedded RegisteredClaims (iss / aud / sub / exp).

It has no groups field and no corti.* fields — which is why the business claims appear in §3 rather than here.

corticph/gocomo/maestro is the other one, and it does parse the business claims — BillingContext embeds RegisteredClaims plus azp, client_id, email, groups, and a nested Corti struct. Because it ships as HTTP middleware (BillingContextMiddleware), copilot-api, audio-bridge and agent-api each parse the same token twice: once through maestro for billing, once through their own pkg/auth struct for request handling. Consolidating those two parsers is the obvious follow-up, and is why maestro is sequenced first in the migration workstreams.

6. Non-consumers

These repos surface in a code search for token fields but are not runtime consumers — they match only via vendored OpenAPI specs, generated SDK clients, indirect dependencies, debug scripts, or because they produce tokens:

• api-specs — spec definitions only
• assistant-ios — generated SDK, mirrors the spec
• ml-service-llm-reasoning — extracts console_project_id for Opik trace metadata only (observability, not functional)
• local-pilot — debug jq scripts that print claims for local testing
• agent-memory — JWT is an indirect dependency

7. Using this when changing the token

When a claim is about to be renamed, moved, or removed:

1. Find the readers — locate the claim in §2 / §3, then confirm in the repos with gh search code '<claim>' --owner corticph.
2. Check the struct tag — the consumer's JSON tag must match the produced claim name exactly (see the §3 note on stripe_id and is_nfr,string).
3. Confirm CC vs delegated presence — a claim present on CC tokens may be absent on delegated tokens (notably corti.console_project_id); a consumer without a groups fallback only works for the family that carries the claim.
4. Mind the gateway — verification lives in the Envoy SecurityPolicy in the charts repo, and the traefik deny-jwt-scope plugin fails open; changes to iss / scope affect routing and the deny-list, not just business logic.
5. Expect arrays, not scalars — anything moving to organization.<org> becomes an array (id excepted), and unset values arrive as the literal string "null" rather than a missing key. A consumer that only changes the claim path and keeps a scalar type will fail to decode. See the parsing contract in Platform Mappers Contract §6.