--- title: SCIM v2.0 --- Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other instance resources. By implementing the official *System for Cross-domain Identity Management (SCIM) v2.0* specification, Zitadel allows seamless and automated user creation, updates, deactivation, and deprovisioning across systems. ## API For full reference details of Zitadel’s SCIM API, consult the API documentation [here](/apis/scim2). ## Provisioning domain A **provisioning domain** represents an external administrative domain—separate from the service provider—typically introduced for legal, organizational, or technical reasons. Refer to the SCIM specification definitions in **RFC7643**: https://datatracker.ietf.org/doc/html/rfc7643#section-1.2 Zitadel uses provisioning domains to scope the handling of the SCIM **`externalId`**, ensuring that different customers or systems provisioning users do not conflict with each other. ### Setting a provisioning domain A provisioning domain can be assigned to a **service account** by adding the following metadata entry: - **Key:** `urn:zitadel:scim:provisioningDomain` - **Value:** the name of the provisioning domain ### How Zitadel stores `externalId` If a service account has a provisioning domain set, any SCIM `externalId` provided during user provisioning or lookup is stored under: `urn:zitadel:scim:{provisioningDomain}:externalId` If *no* provisioning domain is configured, Zitadel falls back to a simplified metadata key: `urn:zitadel:scim:externalId` This ensures that different provisioning sources remain isolated, and the correct `externalId` is returned when queried through SCIM. ## Mapping The following table describes how Zitadel maps SCIM User attributes to Zitadel user fields. Attributes without a direct Zitadel equivalent are stored in **user metadata**. For more information about user metadata, see [here](../customize/user-metadata). | SCIM | Zitadel | Remarks | |------------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | `userId` | | | `username` | `username` | | | `name.formatted` | `profile.displayName` | The SCIM attribute `displayName` takes precedence over `name.formatted` | | `name.familyName` | `profile.familyName` | | | `name.middleName` | `metadata[urn:zitadel:scim:name.middleName]` | | | `name.honorificPrefix` | `metadata[urn:zitadel:scim:name.honorificPrefix]` | | | `name.honorificSuffix` | `metadata[urn:zitadel:scim:name.honorificSuffix]` | | | `displayName` | `profile.displayName` | The SCIM attribute `displayName` takes precedence over `name.formatted` | | `nickName` | `profile.nickName` | | | `profileUrl` | `metadata[urn:zitadel:scim:profileUrl]` | | | `title` | `metadata[urn:zitadel:scim:title]` | | | `preferredLanguage` | `profile.preferredLanguage` | | | `locale` | `metadata[urn:zitadel:scim:locale]` | | | `timezone` | `metadata[urn:zitadel:scim:timezone]` | | | `active` | `state` | `Initial` and `Active` are mapped to `active = true`, all other states are mapped to `active = false`.
The `active` value can only be updated if the user is in the state `Active` or `Inactive`. | | `password` | `password` | | | `emails` | `email` | Only the `primary` email is stored in Zitadel, if there is no `primary` email, the first one is stored. By default emails from SCIM are considered verified, this can be adjusted in the [settings](#settings). | | `phoneNumbers` | `phone` | Only the `primary` phone number is stored in Zitadel, if there is no `primary` phone number, the first one is stored. By default phone numbers from SCIM are considered verified, this can be adjusted in the [settings](#settings). | | `ims` | `metadata[urn:zitadel:scim:ims]` | Serialized as JSON. | | `photos` | `metadata[urn:zitadel:scim:photos]` | Serialized as JSON. | | `addresses` | `metadata[urn:zitadel:scim:addresses]` | Serialized as JSON. | | `entitlements` | `metadata[urn:zitadel:scim:entitlements]` | Serialized as JSON. | | `roles` | `metadata[urn:zitadel:scim:roles]` | Serialized as JSON. | | `externalId` | `metadata[urn:zitadel:scim:externalId]`
`metadata[urn:zitadel:scim:{provisioningDomain}:externalId]` | See [provisioning domain](#provisioning-domain). | ## Settings This section provides details on the runtime settings of the SCIM interface of Zitadel. ### Defaults - Emails from SCIM are treated as **verified** - Phone numbers from SCIM are treated as **verified** - Bulk SCIM operations can include up to **100 operations** - Maximum SCIM request body size is **1 MB** This behavior can be adjusted through the Zitadel runtime settings: ```yaml SCIM: EmailVerified: true PhoneVerified: true MaxRequestBodySize: 1_000_000 Bulk: MaxOperationsCount: 100 ``` ## Limitations Zitadel’s SCIM implementation follows the core SCIM specification but includes the following limitations. ### Supported schemas Zitadel currently supports only the SCIM User schema: `urn:ietf:params:scim:schemas:core:2.0:User` Group provisioning and other extended schemas are not supported. ### Required attributes In addition to SCIM-standard required fields, Zitadel requires: * `name.familyName` * `name.givenName` * `emails`: at least one email is required ### Duplicated attribute mapping The SCIM user attributes `name.formatted` and `displayName` are both mapped to the `profile.displayName` attribute in Zitadel. If both are provided, `displayName` always takes precedence and is the value that will be stored and returned in future SCIM queries. ## Resources - **[Zitadel SCIM API Documentation](/apis/scim2)**: Documentation of Zitadel's SCIM API implementation. - **[SCIM](https://scim.cloud/)**: The Webpage of SCIM. - **[RFC7643](https://tools.ietf.org/html/rfc7643) Core Schema**: The Core Schema provides a platform-neutral schema and extension model for representing users and groups. - **[RFC7644](https://tools.ietf.org/html/rfc7644) Protocol**: The SCIM Protocol is an application-level, REST protocol for provisioning and managing identity data on the web. - **[RFC7642](https://tools.ietf.org/html/rfc7642) Definitions, Overview, Concepts, and Requirements**: This document lists the user scenarios and use cases of System for Cross-domain Identity Management (SCIM).