Skip to content
Authrim

Preview or restore the before value of one recorded level change.

POST
/api/admin/identity-mapping/history/{id}/restore
Code sample: Shell / cURL 
curl --request POST \
  --url https://auth.example.com/api/admin/identity-mapping/history/example/restore \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "preview": true }'

Restores only the tenant default or the named client’s identity_mapping choice, through the same validation and write path as a normal save. It does not restore set contents. Both preview and execution require the permission for the entry’s level: tenant settings edit authority for a tenant default, or clients update access for an app. Agents cannot use this operation. An entry of another tenant is not found. Previewing a tenant default also needs clients read access because it lists affected apps. Preview writes nothing and returns the current choice, the target choice, later changes to the same level, affected apps and the version to submit. Later changes produce a warning and do not prevent a confirmed restore. Execution rechecks the version and set availability (a change away and back still invalidates the preview); conflicts require a new preview. The restore itself creates a new history entry with via restore. Only the exact body {“preview”:true} remains available while release mutations are paused or rollout status is unavailable. The apps preview is bounded to 200 rows, 20 distinct selections and 20 resolved content versions across both sides, and later changes to 100 rows and 20 distinct target choices; truncation flags identify incomplete lists. Rate limited with the strict profile.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string
>= 8 characters <= 128 characters /^[a-zA-Z0-9_-]{8,128}$/

Request Body required

Section titled “Request Body required ”
Media type application/json
One of:
object
preview
required
boolean
key
additional properties

Responses

Section titled “ Responses ”

200

Section titled “200 ”

A read-only preview, or confirmation that the choice was restored.

Media type application/json
One of:
object
entry
required
object
id
required
string
tier
required
string
Allowed values: tenant_default client
client_id
required
string | null
before
required
One of:
object
state
required
string
Allowed values: unset none invalid
key
additional properties
after
required
One of:
object
state
required
string
Allowed values: unset none invalid
key
additional properties
actor_id
required
string
actor_type
required
string
via
required
string
Allowed values: settings client bulk_apply restore
bulk_id
required
string | null
created_at
required

Unix time in milliseconds.

integer
source_version
required

The version of the level after this change.

string
restorable
required
boolean
not_restorable_reason
string
Allowed values: set_deleted set_inactive is_current client_deleted invalid_history
key
additional properties
current
required
One of:
object
state
required
string
Allowed values: unset none invalid
key
additional properties
restores
required
One of:
object
state
required
string
Allowed values: unset none invalid
key
additional properties
later_changes
required
Array<object>
<= 100 items
object
id
required
string
tier
required
string
Allowed values: tenant_default client
client_id
required
string | null
before
required
One of:
object
state
required
string
Allowed values: unset none invalid
key
additional properties
after
required
One of:
object
state
required
string
Allowed values: unset none invalid
key
additional properties
actor_id
required
string
actor_type
required
string
via
required
string
Allowed values: settings client bulk_apply restore
bulk_id
required
string | null
created_at
required

Unix time in milliseconds.

integer
source_version
required

The version of the level after this change.

string
restorable
required
boolean
not_restorable_reason
string
Allowed values: set_deleted set_inactive is_current client_deleted invalid_history
key
additional properties
later_changes_truncated
required
boolean
apps
required
Array<object>
<= 200 items
object
tenant_id
required
string
client_id
required
string
name
required
string
tier
required
string
Allowed values: client tenant_default platform_default none
changes
required
Array<object>
object
kind
required

profile_field_*: the set’s one Destination Profile is switched for another, and the new one lists a claim the old did not (or no longer lists it, or with other scopes, surfaces or requirement), even one no edge writes (the standard claims pass the profile too). validation_changed names the validated field, not necessarily a released claim; its validation_change and validation_effect describe the definition change and whether it may reject an app’s whole issuance.

string
Allowed values: added removed renamed profile_changed source_changed transform_changed type_changed validation_changed profile_field_added profile_field_removed profile_field_changed
claim
required
string
namespace
required

The namespace the claim is written in; the runtime releases an app’s claims from oidc.claim, or from the namespace the app’s own choice names.

string
previous_namespace

renamed: the namespace before, when it differs.

string
previous_claim

renamed: the claim’s name before.

string
type_before

Catalog type summary; multiple source types are separated by |.

string
type_after

Catalog type summary; multiple source types are separated by |.

string
source_types_before

For a type change involving multiple sources, each source’s catalog type before. Unknown types are null. Source names are namespace and path separated by a colon.

Array<object>
object
source
required
string
type
required
string | null
key
additional properties
source_types_after

Each source’s catalog type after, when source_types_before is present.

Array<object>
object
source
required
string
type
required
string | null
key
additional properties
validation_change

For validation_changed, whether the validated field gained, lost, or changed its validation definitions. Rule parameters and attribute values are never returned.

string
Allowed values: added removed changed
validation_effect

May_reject means a critical validation definition changed, so issuance can fail or recover independently of release scopes and namespace. It appears in every app’s changes. validation_only means only noncritical definitions changed, so it is listed only in the set’s changes and never in held_back. Omitted severity is stored as error.

string
Allowed values: may_reject validation_only
profile_id
required
string | null
previous_profile_id

profile_changed: the profile before.

string | null
key
additional properties
held_back
required
Array<object>
object
claim
required
string
scope
required
string | null
key
additional properties
before
required
object
tenantId
required
string
clientId
required

The app asked about; null for the tenant’s view.

string
nullable
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
chain
required

The app’s level, the tenant default and the platform default, in that order.

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

Given with a selection of none because nothing is named (no_default); empty otherwise. implicit_activation_no_longer_applies: the tenant has active activations that fit an OIDC call (for an app, one that names it counts too), which the release used to apply to an app naming no Mapping Set and no longer does. Name the Mapping Set as the tenant’s default (or the app’s own) to keep what they did. Only this tenant’s rows are read, and only IDs and names are given.

Array<object>
object
code
required
string
Allowed values: implicit_activation_no_longer_applies
activations
required
Array<object>
object
activationId
required
string
setId
required
string
setName
string
key
additional properties
key
additional properties
warnings_unavailable

The Admin database could not be read to look for the activations, so warnings is empty without the tenant having none.

boolean
key
additional properties
after
required
object
tenantId
required
string
clientId
required

The app asked about; null for the tenant’s view.

string
nullable
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
chain
required

The app’s level, the tenant default and the platform default, in that order.

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

Given with a selection of none because nothing is named (no_default); empty otherwise. implicit_activation_no_longer_applies: the tenant has active activations that fit an OIDC call (for an app, one that names it counts too), which the release used to apply to an app naming no Mapping Set and no longer does. Name the Mapping Set as the tenant’s default (or the app’s own) to keep what they did. Only this tenant’s rows are read, and only IDs and names are given.

Array<object>
object
code
required
string
Allowed values: implicit_activation_no_longer_applies
activations
required
Array<object>
object
activationId
required
string
setId
required
string
setName
string
key
additional properties
key
additional properties
warnings_unavailable

The Admin database could not be read to look for the activations, so warnings is empty without the tenant having none.

boolean
key
additional properties
before_unavailable

The current choice cannot issue mapped claims. The preview uses an empty mapping as the before side of the claim comparison so a usable earlier choice can still be restored. Database failures are not treated as an empty mapping, and the restored choice must still resolve successfully.

string
Allowed values: set_missing set_inactive destination_profile_invalid
key
additional properties
apps_truncated
required
boolean
expected_version
required
string
warning
string
Allowed value: later_changes_will_be_overwritten
key
additional properties
Example 
{
  "entry": {
    "tier": "tenant_default",
    "before": {
      "state": "unset"
    },
    "after": {
      "state": "unset"
    },
    "via": "settings",
    "not_restorable_reason": "set_deleted"
  },
  "current": {
    "state": "unset"
  },
  "restores": {
    "state": "unset"
  },
  "later_changes": [
    {
      "tier": "tenant_default",
      "before": {
        "state": "unset"
      },
      "after": {
        "state": "unset"
      },
      "via": "settings",
      "not_restorable_reason": "set_deleted"
    }
  ],
  "apps": [
    {
      "tier": "client",
      "changes": [
        {
          "kind": "added",
          "validation_change": "added",
          "validation_effect": "may_reject"
        }
      ],
      "before": {
        "selection": {
          "kind": "bound",
          "tier": "client",
          "setOwner": "tenant"
        },
        "chain": [
          {
            "tier": "client",
            "state": "unset",
            "source": "kv",
            "setOwner": "tenant"
          }
        ],
        "warnings": [
          {
            "code": "implicit_activation_no_longer_applies"
          }
        ],
        "warnings_unavailable": true
      },
      "after": {
        "selection": {
          "kind": "bound",
          "tier": "client",
          "setOwner": "tenant"
        },
        "chain": [
          {
            "tier": "client",
            "state": "unset",
            "source": "kv",
            "setOwner": "tenant"
          }
        ],
        "warnings": [
          {
            "code": "implicit_activation_no_longer_applies"
          }
        ],
        "warnings_unavailable": true
      },
      "before_unavailable": "set_missing"
    }
  ],
  "warning": "later_changes_will_be_overwritten"
}

400

Section titled “400 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

401

Section titled “401 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

403

Section titled “403 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

404

Section titled “404 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

409

Section titled “409 ”

The version or restoration target has changed; obtain a fresh preview.

Media type application/json
object
error
required
string
Allowed value: conflict
reason
required
string
Allowed values: version_conflict set_deleted set_inactive is_current client_deleted invalid_history
error_description
string
Example 
{
  "error": "conflict",
  "reason": "version_conflict"
}

429

Section titled “429 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Section titled “503 ”

Storage or rollout state is unavailable. A temporarily_unavailable response may include operation_id when the client update has committed but its history still needs confirmation. A retry must first read current state rather than assume the choice was unchanged.

Media type application/json
object
error
string
error_description
string
operation_id
string
Example generated
{
  "error": "example",
  "error_description": "example",
  "operation_id": "example"
}