Replace the content of a Mapping Set, and switch it on or off.
curl --request PUT \ --url 'https://auth.example.com/api/admin/identity-mapping/sets/example?preview=false' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "display_name": "example", "description": "example", "field_mapping_key": "example", "owner_scope_type": "tenant", "enabled": true, "confirm_impact": 1, "content": { "catalogVersionId": "example", "compatibilityRange": "example", "sourceProfileIds": [ "example" ], "rules": [ { "additionalProperty": "example" } ] } }'Replaces the whole content of a Mapping Set that exists (a set cannot be created by naming its ID: use POST /api/admin/identity-mapping/sets) in one call, instead of the version, publish, compile and activate calls. The control plane’s own steps run in order, and none of their checks is repeated here: the content is validated first (what the version create checks, what the compile checks, and the release safety check the activation makes, which is run now so that nothing is saved that cannot be switched on; a platform set is also held to what a platform set may hold), then a new version is created, published and compiled, and last the version in use is replaced by it (enabled, true by default) in the control plane’s one atomic switch, or, with enabled: false, the activation is ended. Every save makes a new version; the earlier ones are kept. An activation written here is scoped to OIDC and the OP role ({protocol: oidc, role: op}; a platform set is written with an empty scope, as the activation endpoint does). A set that releases into a Destination Profile that is not an OIDC one, none, or more than one, is refused with 400 unsupported_destination (or invalid_request for more than one OIDC profile): use the field mapping version and activation endpoints for those. If-Match (optional) carries the content_version (or ETag) read last; another value is a 409 conflict, and so is a set that is saved by someone else while this save is built. While something names the set (an app, a default, a SAML provider, a credential profile, SCIM), confirm_impact has to carry the number of references (references.count of the preview or of GET /api/admin/identity-mapping/usage); without it, or with another number, 409 impact_confirmation_required with references. Switching a set that is named off is refused as the deactivation endpoint refuses it (409, reason referenced), and a version that would not meet what the references need as the activation endpoint does (would_break_references, scan_incomplete). When a step fails the answer carries stage_failed (validate, create_version, publish, compile or activate), the status of the failure, and version_id of the version this save created together with version_discarded (the version is removed when it can be); the version in use stays in use, and the name and description are put back. A refusal before the steps (authority, 404, If-Match, confirm_impact, the shape of the request) carries no stage_failed. ?preview=true writes nothing (no version, no settings document, no replay record, no backup admission) and answers 200 with the result of the validation (valid, or valid: false with stage_failed, error and error_description), whether it would compile, the difference from the content now (the sizes and the names of the claims added and removed, never a value), the number of references, whether confirm_impact is required, and whether switching the set off would be refused; whether the new version may replace the one in use is judged when it has a compiled snapshot, on the save. Saves that run at the same time do not overwrite each other: the version in use that the save was decided against is checked again with the activation lock held and again inside the batch that switches (the switch fails as a whole when it is another version now), and the loser answers 409 conflict with stage_failed activate, its own version removed and the other save untouched. The name and description are written by that same batch, never before, so a save that loses leaves them as the other save made them. The number of references is compared with confirm_impact again just before the switch (409 impact_confirmation_required with the newest count, stage_failed activate); an app that comes to name the set after that last look cannot be excluded, because the references live in other databases than the set. A version that was being written when a step failed is removed by one batch that first checks that nothing put it in use meanwhile. A save that leaves the set off is confirmed by one batch that checks that nothing was saved or switched on since it looked (else 409 conflict). When the answer of that batch (or of the switch) is lost, the state is looked at: if the save’s own mark is there it stands and the answer is 200; if the state cannot be read the answer is 500 outcome_unknown (stage_failed activate) with nothing cleaned up, and the key is held (a repeat is 409 result_unknown). A version that another call put in use first (the activation endpoint) is not taken for this save’s own switch: 409 conflict, and the scope that call wrote stands. A repeat of a deletion that succeeded is answered with the stored result although the set is gone, judged by the owner the stored answer records (a platform set’s needs platform authority). One audit record is made for a save (identity_mapping.set.saved: the set, the version, enabled, the result, the number of rules; never a value). A platform set needs platform authority (403 otherwise). A set another tenant owns, and one that does not exist, answer 404. Idempotency-Key is required (8 to 128 characters; not for a preview): the same key, method, path and body answers with the stored result (and its ETag) for 15 minutes in the Admin database; the same key for another request, or from another credential or with other rights than the first request (the stored answer is for the authority it was made with), is 409 idempotency_conflict; the right to change the set is judged again before a stored answer is used (403 / 404 as for a first request); and a request that started but whose result was lost is 409 result_unknown. The body is at most 256 KiB (the Admin API’s common limit of 100 KiB does not apply to this route), and the content is held to the limits of the version create. Rate limited with the strict profile.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Mapping Set identifier.
Header Parameters
Section titled “Header Parameters ”Required replay-protection key retained for 15 minutes.
The content_version (or ETag) of the set as it was read.
Query Parameters
Section titled “Query Parameters ”With true nothing is written; the answer says what the save would do (see the PUT).
Request Body required
Section titled “Request Body required ”object
Required to create (unique among the owner’s sets). On a PUT it can be left out or must be the set’s own key.
Only when creating: platform creates the platform’s set (platform authority). On a PUT it can be left out or must be the set’s owner.
True switches the saved version on, in place of the one in use. False saves it and ends the activation (refused while something names the set).
The number of references seen last (preview or usage). Required to change a set that something names.
What a version holds, in the form the version create takes (camelCase), and the catalog version it is compiled against. The version label and the author are made by the server.
object
The catalog version the content is compiled against.
Source Profile references validated for mappingRequired fields. Not given back by a GET (the edges carry the profile IDs).
Rules with ruleKey, ruleKind, action, priority, scope, condition, metadata, edges (sourceRef, targetRef, edgeKind), transforms (edgeIndex, operation, parameters), validationRules, releaseRules and conflictRules, as in FieldMappingVersionCreateRequest. The rules release into exactly one OIDC Destination Profile (named by targetRef.profileId).
object
Responses
Section titled “ Responses ”The set was saved (200 for a set that existed, 201 for one that was created), or, with preview=true, what a save would do.
object
Whether an activation is in use.
The label of the version the set is now (the one in use, else the last saved).
What the set is now: the ID of the version in use, else of the version saved last, else none. Changes with every save; sent as If-Match.
The version this save created.
object
The names of the claims released. Never a value.
object
Only when valid is false.
Only when valid is false.
Only when valid is false.
object
object
object
object
Why switching the set off would be refused now, if it would.
object
object
object
The names of the claims released. Never a value.
object
The names of the claims released. Never a value.
object
Example
{ "owner": "tenant"}Headers
Section titled “Headers ”The content_version after the save, quoted.
The save was refused or a step failed. stage_failed names the step when the content was looked at or written; version_id and version_discarded are given when a version was created.
object
For example invalid_request, unsupported_destination, conflict, impact_confirmation_required, idempotency_conflict, result_unknown, internal_error.
The version this save created before it failed.
Whether that version was removed.
The references that made a change a conflict, as in MappingSetInUseError; for impact_confirmation_required, references.count is the number to confirm.
object
Example
{ "stage_failed": "validate", "reason": "referenced"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}The save was refused or a step failed. stage_failed names the step when the content was looked at or written; version_id and version_discarded are given when a version was created.
object
For example invalid_request, unsupported_destination, conflict, impact_confirmation_required, idempotency_conflict, result_unknown, internal_error.
The version this save created before it failed.
Whether that version was removed.
The references that made a change a conflict, as in MappingSetInUseError; for impact_confirmation_required, references.count is the number to confirm.
object
Example
{ "stage_failed": "validate", "reason": "referenced"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}The save was refused or a step failed. stage_failed names the step when the content was looked at or written; version_id and version_discarded are given when a version was created.
object
For example invalid_request, unsupported_destination, conflict, impact_confirmation_required, idempotency_conflict, result_unknown, internal_error.
The version this save created before it failed.
Whether that version was removed.
The references that made a change a conflict, as in MappingSetInUseError; for impact_confirmation_required, references.count is the number to confirm.
object
Example
{ "stage_failed": "validate", "reason": "referenced"}Error response.
object
Example generated
{ "error": "example", "message": "example", "error_description": "example"}