Identity Mapper Set APIs enable developers to manage Identity Mapper Sets programmatically as part of a Config-as-Code workflow. These APIs are designed for automation, version control, and Environment promotion rather than interactive configuration.
Instead of defining and maintaining Mapper Sets only through the UI, the APIs allow teams to export, store, review, and apply Mapper Set definitions consistently across Environments and Scopes.
This article explains how to work with Identity Mapper Sets using APIs, how the operations fit together, and how they are typically used in real-world development workflows.
Before creating a Mapepr Set, ensure that an Identity Source exists in your Template. Identity Sources can be created through the Import Identity Sources API call or through the Identity Sources section in the Platform UI.
For documentation on how to manage Mapper Sets in the UI, refer to Identity Mapper Sets.
Why Use Identity Mapper Set APIs
Identity Mapper Set APIs are intended for teams that treat Identity configuration as code. Common use cases include:
- Keeping Identity mapping logic under source control.
- Promoting the same mapping logic across development, staging, and production Environments.
- Reviewing mapping changes through pull requests.
- Automating onboarding of new Identity Templates.
- Renaming or restructuring Mapper Sets without manually rebuilding mappings.
The APIs operate at the configuration layer. They do not affect logical Identity modeling or Policy logic, but they directly control how Identity Attributes are populated in each context.
See the following table for more information about each API call.
| API Call | Purpose | Use Cases |
|---|---|---|
| List Identity Mapper Sets | Returns a summary of all Mapper Sets defined for an Identity Template. | Discover which Mapper Sets exist for an Identity Template, identify the correct Mapper Set ID, or verify configuration after changes. You can also retrieve the full data set using the detailed query parameter. |
| Import Identity Mapper Set | Creates a new Mapper Set or updates an existing one using a declarative definition. | Apply Mapper Set definitions stored in source control, promote configurations across Environments, or update mapping logic without redefining Identity Templates. |
| Export Identity Mapper Set | Retrieves the full definition of a specific Mapper Set. | Capture existing Mapper Set configurations, review or audit mapping logic, or use an existing Mapper Set as a baseline for new configurations. You can extract the Identity Mapper Set ID from the List Mapper Sets API call. |
| Update Identity Mapper Set ID | Renames a Mapper Set without changing its content or associations. | Align Mapper Set identifiers with naming conventions, refactor configuration IDs during migrations, or standardize identifiers across Environments. |
| Delete Identity Mapper Set | Removes a Mapper Set and all its mappings. | Remove deprecated or unused Mapper Sets, reduce configuration clutter, or retire mapping profiles that are no longer associated with any Scope. |
Updating Mapper Sets
When updating an existing Mapper Set using the import operation:
- If the Mapper Set ID already exists, the Mapper Set content is updated.
- If the Mapper Set ID does not exist, a new Mapper Set is created.
This approach allows you to apply updates declaratively without checking the current state beforehand.
When renaming a Mapper Set, use the update operation rather than deleting and recreating the Mapper Set. This preserves references and avoids breaking existing Scope associations.
Identity Mapper Set APIs provide a declarative and automation-friendly way to manage Identity resolution logic. They allow developers to:
- Treat mapping definitions as code.
- Promote configurations across Environments.
- Update or rename Mapper Sets safely.
- Maintain consistency without duplicating Identity Templates.
When used with source control and CI or CD pipelines, these APIs support scalable management of Identity Mapper Sets across the full configuration lifecycle.