Explain, for a test user, why an app gets or does not get each claim.

POST

/api/admin/identity-mapping/explain

Shell / cURL

curl --request POST \
  --url https://auth.example.com/api/admin/identity-mapping/explain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "example", "subject": { "kind": "test_user", "id": "example" }, "surface": "id_token", "scopes": [ "example" ], "consent": "all", "claims": [ "example" ] }'

Runs the release of claims the token endpoint (the code flow’s ID token, no claims parameter) or UserInfo runs for the app, for one of the tenant’s test users: the claims the endpoint starts from (evaluateClaimsForTarget), then applyOIDCIdentityMapping with the same surface, scopes, claims and source attributes. The release is told that the subject is a test user, so nothing is looked up by its ID (no consent record, custom field or persistent identifier secret), and its consent to the Destination Profile’s optional fields is consent (all by default, or none). The answer gives the selection and its levels (as the effective endpoint), the warnings of an activation that no longer applies, the outcome (issued, or stopped with the code of what stopped the release and, for a value the profile refused, the claim), and one line per claim: where it comes from, whether the test user has a value (never the value), the scope that releases it and whether it was granted, the consent, whether it was released and, if not, a fixed reason. A claim made from a persistent identifier is not_evaluated and its released is null. Only test users are explained: a real person is the investigations’ entrance. Needs the settings read and the clients read permissions. Rate limited with the strict profile.

Authorizations

adminBearer
adminSessionCookie

Request Body^required

application/json

object

client_id

required

string

>= 1 characters <= 256 characters

subject

required

object

kind

required

string

Allowed values: test_user

required

string

key

additional properties

surface

required

string

Allowed values: id_token userinfo

scopes

The scopes granted. Left out: the app’s registered scopes, with openid.

Array<string>

<= 50 items

consent

The test user’s selection of the Destination Profile’s optional fields.

string

default: all

Allowed values: all none

claims

More claims to explain (one the app expects and the set may not give).

Array<string>

<= 50 items

key

additional properties

Responses

200

Why each claim is or is not released for the test user.

application/json

object

tenantId

required

string

clientId

required

string

surface

required

string

Allowed values: id_token userinfo

subject

required

object

kind

required

string

Allowed values: test_user

user_id

required

string

key

additional properties

scopes

required

Array<string>

consent

required

string

Allowed values: all none

selection

required

One of:

object

kind

required

string

Allowed values: bound

tier

required

string

Allowed values: client tenant_default platform_default

setId

required

string

pinnedVersionId

The version the app’s own choice pins, if it does.

string

setFound

boolean

setName

string

setOwner

string

Allowed values: tenant platform

setLifecycleState

string

object

kind

required

string

Allowed values: failed

code

required

A level is set and not usable. The selection does not fall to the next level. settings_unreadable (no tier: the settings decide both defaults) is given only in the list of every tenant, for a tenant whose settings could not be read; the effective endpoint answers 503 instead.

string

Allowed values: default_setting_invalid client_selector_invalid settings_unreadable proposal_refused

tier

string

Allowed values: client tenant_default platform_default

reason

A fixed code for what failed underneath. legacy_profile_only_selector: the app’s own choice names a Destination Profile (destinationProfileId) and no Mapping Set and no opt-out, a selector of the older kind, which is not a choice; the release fails for the app (400 invalid_client) rather than lose the profile’s gate in silence (select a Mapping Set or save { "mode": "none" }). With settings_unreadable, the code of the read that failed (unknown when it has none).

string

chain

required

Array<object>

object

tier

required

string

Allowed values: client tenant_default platform_default

state

required

What the level says. This endpoint reads every level, so unset, set, none and invalid are what is found. not_consulted is given for the two defaults only when they were not read for this answer: the app’s own identity_mapping is not a choice (selection is failed with client_selector_invalid, and nothing below it is looked at), or the app decides (a set, or an opt-out) and the settings that hold the defaults could not be read.

string

Allowed values: unset set none invalid not_consulted

setId

The set the level names, when state is set.

string

source

For the two defaults: kv is saved at the tenant itself, platform is the platform’s value.

string

Allowed values: kv platform tenant env default

setFound

Whether the set exists and the calling tenant may name it (its own or the platform’s). False for a set that does not exist and for another tenant’s. Absent, with the other set* fields, when the Admin database could not be read.

boolean

setName

string

setOwner

string

Allowed values: tenant platform

setLifecycleState

string

warnings

required

As the effective endpoint gives them.

Array<object>

object

key

additional properties

warnings_unavailable

boolean

outcome

required

One of:

object
object

object

kind

required

string

Allowed values: issued

key

additional properties

object

kind

required

string

Allowed values: stopped

code

required

What stopped the release: a selection or set code (set_missing, set_inactive, destination_profile_invalid, admin_database_unavailable, default_setting_invalid, client_selector_invalid, settings_unreadable), a Destination Profile check of a value (required_field_missing, non_nullable_field_null, invalid_field_value, destination_profile_unavailable), a release safety rule (release_safety.*), or a code of the release (policy.*).

string

tier

string

Allowed values: client tenant_default platform_default

claim

The claim whose value the profile refused.

string

key

additional properties

claims

required

Array<object>

object

claim

required

string

field

required

The first attribute the claim is filled from; null for sub and asked claims.

string | null

sources

required

Every attribute the claim is filled from.

Array<string>

origin

required

mapping: the selected set fills it. standard: a claim Authrim gives from the user’s standard attributes. requested: asked about, and neither.

string

Allowed values: standard mapping requested

value

required

Whether the test user has a value as the release saw it (never the value). not_read: the release stopped before reading it. not_evaluated: it comes from a persistent identifier, which is not derived for a test user.

string

Allowed values: present missing empty not_read not_evaluated

scope

required

string | null

scope_granted

required

boolean

consent

required

string

Allowed values: not_required granted missing

released

required

Null for a not_evaluated value that nothing else holds back.

boolean | null

reason

Given when the claim is not released. mapping_not_applied: no Mapping Set applies and the claim is not a standard one. not_in_set: the selected set’s Destination Profile does not list it. surface_not_listed: not released on this surface (the profile lists it for the other, or, with no set, the token endpoint’s ID token carries only the protocol claims).

string

Allowed values: issuance_stopped mapping_not_applied not_in_set surface_not_listed scope_not_granted value_missing value_empty consent_missing

key

additional properties

key

additional properties

Example

{
  "surface": "id_token",
  "subject": {
    "kind": "test_user"
  },
  "consent": "all",
  "selection": {
    "kind": "bound",
    "tier": "client",
    "setOwner": "tenant"
  },
  "chain": [
    {
      "tier": "client",
      "state": "unset",
      "source": "kv",
      "setOwner": "tenant"
    }
  ],
  "outcome": {
    "kind": "issued"
  },
  "claims": [
    {
      "origin": "standard",
      "value": "present",
      "consent": "not_required",
      "reason": "issuance_stopped"
    }
  ]
}

400

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

401

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

403

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

404

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

429

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

500

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Error response.

application/json

object

error

string

message

string

error_description

string

key

additional properties

Example ^generated

{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

Explain, for a test user, why an app gets or does not get each claim.

Authorizations

Request Body required

Responses

200

Example

400

Example generated

401

Example generated

403

Example generated

404

Example generated

429

Example generated

500

Example generated

503

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated