SCIM v2.0 (Preview)

info

The SCIM v2 interface of Zitadel is currently in a preview stage. It is not yet feature-complete, may contain bugs, and is not generally available.

Do not use it for production yet.

As long as the feature is in a preview state, it will be available for free, it will be put behind a commercial license once it is fully available.

The Zitadel SCIM v2 service provider interface enables seamless integration of identity and access management (IAM) systems with Zitadel, following the System for Cross-domain Identity Management (SCIM) v2.0 specification. This interface allows standardized management of IAM resources, making it easier to automate user provisioning and deprovisioning.

Supported endpoints

The Zitadel SCIM v2.0 service provider implementation supports the following endpoints. The base URL for the SCIM endpoint in Zitadel is: https://${ZITADEL_DOMAIN}/scim/v2/{orgId}.

Endpoint	Remarks
`GET /scim/v2/{orgId}/ServiceProviderConfig`	Retrieve the configuration of the Zitadel service provider
`GET /scim/v2/{orgId}/Schemas`	Retrieve all supported schemas
`GET /scim/v2/{orgId}/Schemas/{id}`	Retrieve a known supported schema
`GET /scim/v2/{orgId}/ResourceTypes`	Retrieve all supported resource types
`GET /scim/v2/{orgId}/ResourceTypes/{name}`	Retrieve a known supported resource type
`GET /scim/v2/{orgId}/Users/{id}`	Retrieve a known user
`GET /scim/v2/{orgId}/Users` `POST /scim/v2/{orgId}/Users/.search`	Query users (including filtering, sorting, paging)
`POST /scim/v2/{orgId}/Users`	Create a user
`PUT /scim/v2/{orgId}/Users/{id}`	Replace a user
`PATCH /scim/v2/{orgId}/Users/{id}`	Modify a user
`DELETE /scim/v2/{orgId}/Users/{id}`	Delete a user
`POST /scim/v2/{orgId}/Bulk`	Apply multiple operations in a single request

Authentication

The SCIM interface adheres to Zitadel's standard API authentication methods. For detailed instructions on authenticating with the SCIM interface, refer to the Authenticate Service Users Guide.

Query

The list users endpoint supports sorting and filtering for both GET /scim/v2/{orgId}/Users and POST /scim/v2/{orgId}/Users/.search requests. By default, the response includes up to 100 users, with a maximum allowable value for count set to 100.

Sort

The following attributes are supported in the SortBy attribute.

meta.created
meta.lastModified
id
username
name.familyName
name.givenName
emails and emails.value

Filter

The following filter attributes and operators are supported:

Attribute	Supported operators
`meta.created`	`EQ`, `GT`, `GE`, `LT`, `LE`
`meta.lastModified`	`EQ`, `GT`, `GE`, `LT`, `LE`
`id`	`EQ`, `NE`, `CO`, `SW`, `EW`
`externalId`	`EQ`, `NE`
`username`	`EQ`, `NE`, `CO`, `SW`, `EW`
`name.familyName`	`EQ`, `NE`, `CO`, `SW`, `EW`
`name.givenName`	`EQ`, `NE`, `CO`, `SW`, `EW`
`emails` `emails.value`	`EQ`, `NE`, `CO`, `SW`, `EW`
`active`	`EQ`, `NE`

Filters can have a maximum length of 1000 characters.

Examples

Here are practical examples demonstrating how to interact with the SCIM API, providing clear guidance on common use cases such as creating a user. Make sure to replace any placeholder values (${}) with the actual values from your environment.

POST /Users: Create a minimal user

curl -X POST "https://${DOMAIN}/scim/v2/${ORG_ID}/Users" \
  -H 'Content-Type: application/scim+json' \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "userName": "john.doe",
      "name": {
        "familyName": "Doe",
        "givenName": "John"
      },
      "password": "Password1!",
      "emails": [
        {
          "value": "john.doe@example.com",
          "primary": true
        }
      ]
    }
  '

Response (201 Created)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "meta": {
    "resourceType": "User",
    "created": "2025-01-27T15:30:27.651321Z",
    "lastModified": "2025-01-27T15:30:27.651321Z",
    "version": "2",
    "location": "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/304499468865155777"
  },
  "id": "304499468865155777",
  "userName": "john.doe",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "preferredLanguage": "en",
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true
    }
  ]
}

POST /Users: Create a full user

curl -X POST "https://${DOMAIN}/scim/v2/${ORG_ID}/Users" \
  -H 'Content-Type: application/scim+json' \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
      "userName": "john.doe@example.com",
      "name": {
        "formatted": "Mr. John J Doe, III",
        "familyName": "Doe",
        "givenName": "John",
        "middleName": "Jim",
        "honorificPrefix": "Mr.",
        "honorificSuffix": "III"
      },
      "displayName": "John Doe",
      "nickName": "Johnny",
      "profileUrl": "https://login.example.com/john.doe",
      "emails": [
        {
          "value": "john.doe@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "addresses": [
        {
          "type": "work",
          "streetAddress": "100 Universal City Plaza",
          "locality": "Hollywood",
          "region": "CA",
          "postalCode": "91608",
          "country": "USA",
          "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "+1 555-555-5555",
          "type": "work",
          "primary": true
        }
      ],
      "ims": [
        {
          "value": "@j.doe",
          "type": "X"
        }
      ],
      "photos": [
        {
          "value": "https://photos.example.com/profilephoto/john.doe/F",
          "type": "photo"
        }
      ],
      "roles": [
        {
          "value": "user-admin",
          "display": "User administrator"
        }
      ],
      "entitlements": [
        {
          "value": "read-passports",
          "display": "Read Passports"
        }
      ],
      "userType": "Employee",
      "title": "Tour Guide",
      "preferredLanguage": "en-US",
      "locale": "en-US",
      "timezone": "America/Los_Angeles",
      "active": true,
      "password": "Password1!"
    }'

Response (201 Created)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "meta": {
    "resourceType": "User",
    "created": "2025-01-27T15:31:47.84572Z",
    "lastModified": "2025-01-27T15:31:47.84572Z",
    "version": "16",
    "location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
  },
  "id": "304499603368096449",
  "externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
  "userName": "john.doe@example.com",
  "name": {
    "formatted": "John Doe",
    "familyName": "Doe",
    "givenName": "John",
    "middleName": "Jim",
    "honorificPrefix": "Mr.",
    "honorificSuffix": "III"
  },
  "displayName": "John Doe",
  "nickName": "Johnny",
  "profileUrl": "https://login.example.com/john.doe",
  "title": "Tour Guide",
  "preferredLanguage": "en-US",
  "locale": "en-US",
  "timezone": "America/Los_Angeles",
  "active": true,
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+15555555555",
      "primary": true
    }
  ],
  "ims": [
    {
      "value": "@j.doe",
      "type": "X"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "streetAddress": "100 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "USA",
      "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
      "primary": true
    }
  ],
  "photos": [
    {
      "value": "https://photos.example.com/profilephoto/john.doe/F",
      "type": "photo"
    }
  ],
  "entitlements": [
    {
      "value": "read-passports",
      "display": "Read Passports"
    }
  ],
  "roles": [
    {
      "value": "user-admin",
      "display": "User administrator"
    }
  ]
}

GET /Users/{id}: Retrive a known user

curl -G "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response (200 OK)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "meta": {
    "resourceType": "User",
    "created": "2025-01-27T15:31:47.84572Z",
    "lastModified": "2025-01-27T15:31:47.84572Z",
    "version": "16",
    "location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
  },
  "id": "304499603368096449",
  "externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
  "userName": "john.doe@example.com",
  "name": {
    "formatted": "John Doe",
    "familyName": "Doe",
    "givenName": "John",
    "middleName": "Jim",
    "honorificPrefix": "Mr.",
    "honorificSuffix": "III"
  },
  "displayName": "John Doe",
  "nickName": "Johnny",
  "profileUrl": "https://login.example.com/john.doe",
  "title": "Tour Guide",
  "preferredLanguage": "en-US",
  "locale": "en-US",
  "timezone": "America/Los_Angeles",
  "active": true,
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+15555555555",
      "primary": true
    }
  ],
  "ims": [
    {
      "value": "@j.doe",
      "type": "X"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "streetAddress": "100 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "USA",
      "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
      "primary": true
    }
  ],
  "photos": [
    {
      "value": "https://photos.example.com/profilephoto/john.doe/F",
      "type": "photo"
    }
  ],
  "entitlements": [
    {
      "value": "read-passports",
      "display": "Read Passports"
    }
  ],
  "roles": [
    {
      "value": "user-admin",
      "display": "User administrator"
    }
  ]
}

GET /Users: List users created after a given date sorted by the creation date

curl -G "https://${DOMAIN}/scim/v2/${ORG_ID}/Users" \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "sortBy=meta.created" \
  --data-urlencode "sortOrder=descending" \
  --data-urlencode "filter=meta.created gt \"2025-01-24T09:22:35.695245Z\""

Response (200 OK)

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "totalResults": 1,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "meta": {
        "resourceType": "User",
        "created": "2025-01-27T15:31:47.84572Z",
        "lastModified": "2025-01-27T15:31:47.84572Z",
        "version": "3",
        "location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
      },
      "id": "304499603368096449",
      "externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
      "userName": "john.doe@example.com",
      "name": {
        "formatted": "John Doe",
        "familyName": "Doe",
        "givenName": "John",
        "middleName": "Jim",
        "honorificPrefix": "Mr.",
        "honorificSuffix": "III"
      },
      "displayName": "John Doe",
      "nickName": "Johnny",
      "profileUrl": "https://login.example.com/john.doe",
      "title": "Tour Guide",
      "preferredLanguage": "und",
      "locale": "en-US",
      "timezone": "America/Los_Angeles",
      "active": true,
      "emails": [
        {
          "value": "john.doe@example.com",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "+15555555555",
          "primary": true
        }
      ],
      "ims": [
        {
          "value": "@j.doe",
          "type": "X"
        }
      ],
      "addresses": [
        {
          "type": "work",
          "streetAddress": "100 Universal City Plaza",
          "locality": "Hollywood",
          "region": "CA",
          "postalCode": "91608",
          "country": "USA",
          "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
          "primary": true
        }
      ],
      "photos": [
        {
          "value": "https://photos.example.com/profilephoto/john.doe/F",
          "type": "photo"
        }
      ],
      "entitlements": [
        {
          "value": "read-passports",
          "display": "Read Passports"
        }
      ],
      "roles": [
        {
          "value": "user-admin",
          "display": "User administrator"
        }
      ]
    }
  ]
}

PATCH /Users/{id}: Set a user inactive

curl -X PATCH "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
  -H 'Content-Type: application/scim+json' \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '
    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
      "Operations": [
        {
          "op": "replace",
          "path": "active",
          "value": false
        }
      ]
    }
  '

Response: 204 No Content

PATCH /Users/{id}: Set the password of a user

curl -X PATCH "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
  -H 'Content-Type: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '
    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
      "Operations": [
        {
          "op": "replace",
          "path": "password",
          "value": "Password2!"
        }
      ]
    }
  '

Response: 204 No Content

PUT /Users/{id}: Replace a full user

curl -X PUT "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
  -H 'Content-Type: application/scim+json' \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
      "userName": "john.doe@example.com",
      "name": {
        "formatted": "Mr. John J Doe, III",
        "familyName": "Doe",
        "givenName": "John",
        "middleName": "Jim",
        "honorificPrefix": "Mr.",
        "honorificSuffix": "III"
      },
      "displayName": "John Doe",
      "nickName": "Johnny",
      "profileUrl": "https://login.example.com/john.doe",
      "emails": [
        {
          "value": "john.doe@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "addresses": [
        {
          "type": "work",
          "streetAddress": "100 Universal City Plaza",
          "locality": "Hollywood",
          "region": "CA",
          "postalCode": "91608",
          "country": "USA",
          "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
          "primary": true
        }
      ],
      "phoneNumbers": [
        {
          "value": "+1 555-555-5555",
          "type": "work",
          "primary": true
        }
      ],
      "ims": [
        {
          "value": "@j.doe",
          "type": "X"
        }
      ],
      "photos": [
        {
          "value": "https://photos.example.com/profilephoto/john.doe/F",
          "type": "photo"
        }
      ],
      "roles": [
        {
          "value": "user-admin",
          "display": "User administrator"
        }
      ],
      "entitlements": [
        {
          "value": "read-passports",
          "display": "Read Passports"
        }
      ],
      "userType": "Employee",
      "title": "Tour Guide",
      "preferredLanguage": "en-US",
      "locale": "en-US",
      "timezone": "America/Los_Angeles",
      "active": true,
      "password": "Password1!"
    }'

Response (200 OK)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "meta": {
    "resourceType": "User",
    "created": "2025-01-27T15:31:47.84572Z",
    "lastModified": "2025-01-27T15:31:47.84572Z",
    "version": "16",
    "location": "https://localhost:8080/scim/v2/303879575732073153/Users/304499603368096449"
  },
  "id": "304499603368096449",
  "externalId": "8d4b51c0-51bd-4386-ae17-79ce5fd36517",
  "userName": "john.doe@example.com",
  "name": {
    "formatted": "John Doe",
    "familyName": "Doe",
    "givenName": "John",
    "middleName": "Jim",
    "honorificPrefix": "Mr.",
    "honorificSuffix": "III"
  },
  "displayName": "John Doe",
  "nickName": "Johnny",
  "profileUrl": "https://login.example.com/john.doe",
  "title": "Tour Guide",
  "preferredLanguage": "en-US",
  "locale": "en-US",
  "timezone": "America/Los_Angeles",
  "active": true,
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+15555555555",
      "primary": true
    }
  ],
  "ims": [
    {
      "value": "@j.doe",
      "type": "X"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "streetAddress": "100 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "USA",
      "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
      "primary": true
    }
  ],
  "photos": [
    {
      "value": "https://photos.example.com/profilephoto/john.doe/F",
      "type": "photo"
    }
  ],
  "entitlements": [
    {
      "value": "read-passports",
      "display": "Read Passports"
    }
  ],
  "roles": [
    {
      "value": "user-admin",
      "display": "User administrator"
    }
  ]
}

DELETE /Users/{id}: Delete a user

curl -X DELETE "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response: 204 No Content

POST /Bulk: Update the password of one user and delete another one

curl -X POST "https://${DOMAIN}/scim/v2/${ORG_ID}/Bulk" \
  -H 'Content-Type: application/scim+json' \
  -H 'Accept: application/scim+json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '
    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
      "Operations": [
        {
          "method": "PATCH",
          "path": "/Users/${USER_ID}",
          "data": {
            "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
            "Operations": [
              {
                "op": "replace",
                "path": "password",
                "value": "Password2!"
              }
            ]
          }
        },
        {
          "method": "DELETE",
          "path": "/Users/${USER_ID2}"
        }
      ]
    }'

Response: 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
  "Operations": [
    {
      "method": "PATCH",
      "location": "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID}",
      "status": "204"
    },
    {
      "method": "DELETE",
      "location": "https://${DOMAIN}/scim/v2/${ORG_ID}/Users/${USER_ID2}",
      "status": "204"
    }
  ]
}

GET /ServiceProviderConfig: Get service provider configuration

curl -G "https://${DOMAIN}/scim/v2/${ORG_ID}/ServiceProviderConfig" \
  -H 'Accept: application/scim+json'

Response: 200 OK

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
  ],
  "meta": {
    "resourceType": "ServiceProviderConfig",
    "location": "https://${DOMAIN}/scim/v2/${ORG_ID}/ServiceProviderConfig"
  },
  "documentationUri": "https://zitadel.com/docs/guides/manage/user/scim2",
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": true,
    "maxOperations": 100,
    "maxPayloadSize": 1000000
  },
  "filter": {
    "supported": true,
    "maxResults": 100
  },
  "changePassword": {
    "supported": true
  },
  "sort": {
    "supported": true
  },
  "etag": {
    "supported": false
  },
  "authenticationSchemes": [
    {
      "name": "Zitadel authentication token",
      "description": "Authentication scheme using the OAuth Bearer Token Standard",
      "specUri": "https://www.rfc-editor.org/info/rfc6750",
      "documentationUri": "https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users",
      "type": "oauthbearertoken",
      "primary": false
    }
  ]
}

Error handling

The SCIM interface uses standard HTTP status codes and error messages to indicate the success or failure of API requests following the error handling guidelines of RFC7644.

In addition to the default SCIM error schema (urn:ietf:params:scim:api:messages:2.0:Error), Zitadel extends the error response with a custom schema, urn:ietf:params:scim:api:zitadel:messages:2.0:ErrorDetail. This schema includes additional attributes, such as the untranslated error message and an error id, which aids pinpointing the source of the error in the system.

Resources

Zitadel SCIM Documentation: Documentation of Zitadel's SCIM implementation, including configuration details and known limitations.
SCIM: The Webpage of SCIM.
RFC7643 Core Schema: The Core Schema provides a platform-neutral schema and extension model for representing users and groups.
RFC7644 Protocol: The SCIM Protocol is an application-level, REST protocol for provisioning and managing identity data on the web.
RFC7642 Definitions, Overview, Concepts, and Requirements: This document lists the user scenarios and use cases of System for Cross-domain Identity Management (SCIM).

Supported endpoints​

Authentication​

Query​

Sort​

Filter​

Examples​

Error handling​

Resources​

Supported endpoints

Authentication

Query

Sort

Filter

Examples

Error handling

Resources