---
title: "Create or update an identity provider"
method: PUT
path: "/organizations/{orgId}/environments/{envId}/domains/{domainKey}/identities"
tags: ["Identity Providers", "Domains"]
---

# Create or update an identity provider

`PUT /organizations/{orgId}/environments/{envId}/domains/{domainKey}/identities`

## Request

- Base URL: `http://localhost:8093/automation`
- URL: `http://localhost:8093/automation/organizations/{orgId}/environments/{envId}/domains/{domainKey}/identities`
- Auth: HTTP bearer

Idempotent create-or-update. Uses the key field in the body to identify the identity provider within the domain. On first apply the identity provider is created; subsequent applies update it. The system flag is immutable; changing it requires deleting and recreating the identity provider. When dryRun is true, the endpoint validates the payload without persisting; the returned identity provider carries a dryRunErrors list (empty on success, populated with validation errors otherwise).

## Path parameters

- `orgId` string, required
- `envId` string, required
- `domainKey` string, required

## Query parameters

- `dryRun` boolean

## Request body

- AutomationIdentityProvider: An identity provider managed under a domain by the Automation API. The key field is the stable, immutable identity used for idempotent create-or-update.
  - `configuration` string: Plugin-specific configuration as a JSON-encoded string. Its shape is defined by the selected identity provider type. Sensitive values, as flagged by the plugin, are returned as ******** in every response; an unset sensitive value is omitted. Sending ******** back on update keeps the stored value; sending it on create is rejected.
  - `createdAt` string, date-time: Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.
  - `domainWhitelist` string[]: Email domains allowed to authenticate through this identity provider. When set, users whose email domain is not listed are rejected.
  - `dryRunErrors` DryRunError[]: Validation errors returned when dryRun is true. Absent when validation succeeds.
    - `message` string
    - `severity` 'error' | 'warning'
  - `groupMapper` object: Group mapper: assigns AM groups based on provider attribute values. Each entry maps a group to the user attribute expressions that grant it.
  - `key` string, required: Stable, immutable identifier for the identity provider within its domain. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. Used to identify the identity provider on create-or-update.
  - `mappers` object: Attribute mappers: maps provider claims to AM user profile attributes.
  - `name` string: Human-readable name of the identity provider.
  - `roleMapper` object: Role mapper: assigns AM roles based on provider attribute values. Each entry maps a role to the user attribute expressions that grant it.
  - `system` boolean: Whether this is the domain's system identity provider. Immutable after creation. When true, only key is required; the identity provider is built from the domains.identities.default.* system settings and the name, type, and configuration fields are ignored.
  - `type` string: Identity provider plugin type identifier. Immutable after creation.
  - `updatedAt` string, date-time: Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

## Response `200`

The created or updated identity provider. When dryRun is true the identity provider includes a dryRunErrors field with any validation errors.

- AutomationIdentityProvider: An identity provider managed under a domain by the Automation API. The key field is the stable, immutable identity used for idempotent create-or-update.
  - `configuration` string: Plugin-specific configuration as a JSON-encoded string. Its shape is defined by the selected identity provider type. Sensitive values, as flagged by the plugin, are returned as ******** in every response; an unset sensitive value is omitted. Sending ******** back on update keeps the stored value; sending it on create is rejected.
  - `createdAt` string, date-time: Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.
  - `domainWhitelist` string[]: Email domains allowed to authenticate through this identity provider. When set, users whose email domain is not listed are rejected.
  - `dryRunErrors` DryRunError[]: Validation errors returned when dryRun is true. Absent when validation succeeds.
    - `message` string
    - `severity` 'error' | 'warning'
  - `groupMapper` object: Group mapper: assigns AM groups based on provider attribute values. Each entry maps a group to the user attribute expressions that grant it.
  - `key` string, required: Stable, immutable identifier for the identity provider within its domain. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. Used to identify the identity provider on create-or-update.
  - `mappers` object: Attribute mappers: maps provider claims to AM user profile attributes.
  - `name` string: Human-readable name of the identity provider.
  - `roleMapper` object: Role mapper: assigns AM roles based on provider attribute values. Each entry maps a role to the user attribute expressions that grant it.
  - `system` boolean: Whether this is the domain's system identity provider. Immutable after creation. When true, only key is required; the identity provider is built from the domains.identities.default.* system settings and the name, type, and configuration fields are ignored.
  - `type` string: Identity provider plugin type identifier. Immutable after creation.
  - `updatedAt` string, date-time: Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

## Other responses

- `400`: Invalid request: a key conflict, a missing required field (name or type) for a non-system identity provider, an attempt to change the immutable system flag, or a second system identity provider for the domain
- `403`: Permission denied
- `404`: Domain not found, or not managed by the Automation API

## Changes

- **2026-09-29** `821321fb3bcf`: 10 info
  - added the new optional `query` request parameter `dryRun`
  - the `domainWhitelist` request property default value `` was added
  - the `groupMapper` request property default value `{}` was added
  - the `mappers` request property default value `{}` was added
  - …6 more

[Operation history](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api/changes/organizations/:orgId/environments/:envId/domains/:domainKey/identities/put.md)

---

[API](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api.md) - [All operations](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gravitee-io/apis/gravitee-io-am-automation-api/revisions/b0b6bdfd65cb?raw)