Platform Mappers Contract

This is the developer-facing companion to Token Mappers. That doc explains the current Keycloak setup from the platform's side; this one tells you, as a consumer of Corti access tokens, exactly what claims you get, under which top-level object, what their types are, and how to parse them — and describes the organization-based target model we are moving to.

1. Who this is for

Engineers writing code that reads a Corti access token (backend services, BFFs, frontends). You care about three things:

1. Which claims exist and what they mean.
2. Which top-level object each claim lives under.
3. How to parse each value without breaking — today they're flat strings; in the target model they're arrays under an organization.

For the platform/Keycloak side — which client has which mapper, where values come from — see Token Mappers. For the consumer side — which repos read which claims and how — see Token Consumers.

2. Today vs target, at a glance

3. Current token shape (today)

Today, custom claims are all under corti and are all strings:

"corti": {
  "stripe_customer_id": "",
  "console_project_id": "",
  "metronome_customer_id": "",
  "openmeter_customer_id": "",
  "console_project_uuid": ""
}

Some of today's values come from Keycloak groups and user attributes (e.g. retention_minutes, isNFR, the user-level metronome_customer_id), and project identity for delegated clients comes from the groups claim path rather than a claim of its own. See Token Mappers for the full current picture. All of these sources are being consolidated — see §7.

4. What's changing — organizations

We are enabling the Keycloak Organizations feature so customers can bring their own SSO (an external identity provider per organization).

• A Console Customer becomes an organization. Keycloak organization groups (a 26.6 feature) sit underneath for departments and label scoping. Naming is 1:1 through the stack — Organization → Group — and Console keeps the user-facing "Customer" label for the organization.
• Every organization has an All group containing all of its end-users, so org-wide template scoping has something to target. Users may be in several groups within their organization.
• A user belongs to exactly ONE organization ⇒ the organization object has exactly one entry. You never have to disambiguate.
• Service accounts and studio users are organization members too. Each project has a hidden organization holding its client-credentials service accounts and studio_user_* accounts, carrying the same project attributes. This is why a client-credentials token carries identity at all.
• Group attributes go away. Everything that was a group attribute (is_nfr, retention_minutes, console_*) becomes an organization attribute. The user-level metronome_customer_id mapper is removed too, and so is the Metronome Customer ID attribute on the user entity — it only ever existed as a fallback for users belonging to no group, and every principal is now an organization member. Nothing should read billing identity off a user attribute after the migration.
• corti narrows to client-level attributes: a per-client retention_minutes override, auto_created, and is_studio_client. Keycloak owns the organization object and client-level values cannot be written into it, so a separate namespace is required.
• Dropped entirely: console_project_uuid, stripe_customer_id, console_distributor_id, openmeter_customer_id.

Because organization attributes cannot be re-mapped through the usual User Attribute claim mappers, Keycloak emits them under the top-level organization object and always as arrays — a property of the feature we can't change. The contract below adapts to that.

5. Target token shape

There is one organization, keyed by its alias. id is a string; every other organization attribute is an array. corti carries client-level values only:

{
  "organization": {
    "gp": {
      "id": "f8d3c4e1-2477-44d7-a85b-d3b43f6b31fa",
      "console_project_id": ["alstertext"],
      "console_customer_id": ["gp"],
      "metronome_customer_id": ["d657c398-ec1d-4e7b-8f9e-3b175712d332"],
      "is_nfr": ["false"],
      "retention_minutes": ["43200"],
      "groups": ["/All"]
    }
  },
  "corti": {
    "retention_minutes": "720",
    "auto_created": "true",
    "is_studio_client": "false"
  }
}

Notes:

• id is a string; every other organization attribute is an array.
• groups holds organization-relative paths (/All, /Weight-Mgmt). There is no platform-api/<project>/<customer> prefix — project and customer identity come from console_project_id and console_customer_id.
• is_nfr and retention_minutes are always present (not "only when true").
• For the two accounts on the department model (BUPA, Aleris), console_customer_id holds the organization name; per-service-line identity is only in groups.

6. The parsing contract

1. There is exactly one organization. Take the single entry of the organization map — don't hardcode the org alias and don't assume there could be several.

2. organization.<org>.id → string. It is the one attribute that is not an array. Special-case it.

3. Every other organization attribute → array. Read element [0], but do it defensively (handle empty/missing).

4. Apply the client-level override. The override rule applies only to the slim client-level set (retention_minutes, auto_created, is_studio_client). For those keys, corti wins:

   effective = corti.<key> ?? organization.<org>.<key>[0]
   

   No other corti.* key is an override. During the dual-emit window the legacy corti.* namespace still carries org-level values like console_project_id and metronome_customer_id — those are stale duplicates of what is now in organization.<org>, not overrides, and must defer to the organization. See §7 for the dual-emit precedence guidance.

5. Unset values are the string "null" (or "false"), never a missing key. Treat value[0] === "null" as "unset". Do not confuse it with JSON null or an empty string.

6. Don't parse groups for identity. organization.<org>.groups is for template/label scoping only. Project and customer identity come from console_project_id and console_customer_id.

7. organization should always be present because the scope is a default scope — but handle its absence explicitly rather than panicking, since a misconfigured client would then have no identity at all.

Per-claim reference (target)

Example — Go

// orgAttr returns element 0 of an organization attribute array, normalising the
// literal "null" default to "" so callers can treat unset uniformly.
func orgAttr(org map[string]any, key string) string {
    if v, ok := org[key].([]any); ok && len(v) > 0 {
        if s, ok := v[0].(string); ok && s != "null" {
            return s
        }
    }
    return "" // missing, empty, or the sentinel "null"
}

// effective applies the client-level override: corti wins over the organization.
func effective(corti, org map[string]any, key string) string {
    if s, ok := corti[key].(string); ok && s != "" {
        return s
    }
    return orgAttr(org, key)
}

orgs, ok := claims["organization"].(map[string]any)
if !ok || len(orgs) == 0 {
    // no organization scope on the token — it has no project identity
    return
}

// exactly one organization: take the single entry
var org map[string]any
for _, raw := range orgs {
    org, _ = raw.(map[string]any)
    break
}
corti, _ := claims["corti"].(map[string]any)

id, _ := org["id"].(string)                        // string
projectID := orgAttr(org, "console_project_id")    // array → element 0
isNFR := orgAttr(org, "is_nfr") == "true"
retention := effective(corti, org, "retention_minutes") // client override wins
_ = id; _ = projectID; _ = isNFR; _ = retention

Example — TypeScript (frontend)

const attr = (org: Record<string, string[]>, key: string) => {
  const raw = (org[key] ?? [])[0];
  return raw === "null" || raw === undefined ? undefined : raw;
};

const orgs = claims.organization ?? {};   // should always be present
const org = Object.values(orgs)[0];       // exactly one entry
if (!org) {
  // no organization scope — no project identity
} else {
  const id = org.id as string;            // string, not an array
  const projectId = attr(org, "console_project_id");
  const customerId = attr(org, "console_customer_id");
  const isNfr = attr(org, "is_nfr") === "true";
  // client-level override wins
  const retention = claims.corti?.retention_minutes ?? attr(org, "retention_minutes");
}

7. Claim migration

8. Decisions and remaining open items

Settled:

• organization is a default client scope, not optional.
• A Console Customer maps to an organization; organization groups are used for departments. BUPA and Aleris are the two department-model exceptions (one Default org, Customers as groups).
• One hidden organization per project holds service accounts and studio users.
• corti survives, narrowed to client-level attributes, and is the override half of the precedence rule.
• Cutover is dual-emit then shrink, per realm.
• Client-credentials tokens do carry organization.* (verified on 26.7.0).

Still open — do not build against these:

• Whether a default organization is auto-created per project, or created by the integrator.
• Whether is_nfr survives the migration at all (it is being phased out).
• The Medatixx migration shape under customer == org.

Full detail and ownership in Organization Migration §10.

9. Conventions & recommendations

• One source per claim, and one precedence rule. Organization attributes are the source of truth; corti exists only for client-level overrides. Nothing is duplicated across namespaces for the same level.
• Accept arrays. Organization attributes are arrays by nature — parse with "element 0 + defensive handling" rather than expecting scalars. id is the only string.
• Don't derive identity from paths. Group paths are scoping labels, not identity. Use console_project_id / console_customer_id.
• Use the shared library. common-service-library's jwtclaims package gains an organization type with the [0]-plus-override helper; prefer it over hand-rolling a struct per service.
• Standardise naming — keep organization attribute keys snake_case.