Support Centre

User Provisioning - User Identity Sync (SCIM)

In this article you will learn :

  • What is User Identity Sync (SCIM)
  • Benefits of using SCIM
  • SCIM terminology
  • How to use SCIM with Sherpany


With Single Sign-on (SSO) users can authenticate in Sherpany using an external Identity Provider. User attributes like Email and Name are updated in Sherpany every time a user logs in.

User Identity Sync builds on top of that and also allows the Enterprise Identity Provider to write User attributes to the Sherpany database whenever necessary (without waiting for a user to login).

REQUIRED Package: Enterprise (with SSO)

Benefits of User Identity Sync

Implementing User Identity Sync brings several advantages to your org.

  • Reduced administrative costs - With User Identity Sync, User details changes only need to be done in one place and reduce time spent by administrators keeping permissions up to date in Sherpany.
  • Leverage existing investment - Many companies use a central LDAP database to manage user identities. You can use the existing system and processes to assign roles in Sherpany. So if a User changes from one department to another that can automatically reflect into permission changes in Sherpany.
  • Increased security - Users changing departments within the company won't have access to resources they are not supposed to see in Sherpany automatically. SCIM also supports offboarding users when they leave the company.


System for Cross-domain Identity Management (SCIM) is a standard for managing user identities across applications.

It is a REST API with a clearly defined structure. Many vendors (such as Microsoft, Github, Slack, and Salesforce) support the SCIM standard and there are libraries available for various programming languages (such as Java, Python).

Sherpany supports SCIM2 (Version 1.x is not supported).

We don't include in-depth technical descriptions about the SCIM API in general in this document, see for details.


Service Provider

The web application that allows editing of identity information over the SCIM protocol.

Sherpany is the Service Provider.


An application that uses the SCIM protocol to manage identity data maintained by the Service Provider.

The Sherpany Enterprise Customer is the Client.

Resource (e.g User)An artifact that is managed by a service provider that contains has attributes, e.g a User.
OrganizationThe Sherpany Customer
UserA person who has access to the Sherpany app.


externalIdmax length 255 characters


Schema: urn:ietf:params:scim:schemas:core:2.0:User

See for the full definition in SCIM. Sherpany supports the following subset:

id85d0c1a8-fda3-4656-b4d3-7bcf8fda6d95Set by Sherpany. A unique unchanging id.

Set by Client. A unique unchanging id assigned to a User. The value must be unique within the Organisation and must match the NameID used in SAML.


activetrue or false

The Users administrative status. A value of true implies that the user is able to log in, while a value of false implies that the user's account has been suspended.

The email of the User. We validate that the domain part ( is on the whitelist of allowed domains for this client.



    "familyName": "Jensen",
    "givenName": "Barbara"

Sherpany uses familyName and givenName (required) from name. Other values are ignored. 



allowed values: en-gb, de-ch, fr-fr, it-it, pt-pt

Optional (falls back to the default value of en-gb)

        "value": "+41791234567",				
        "type": "work"				

Sherpany only uses the first item in the list.


Not supported attributes

Sherpany User Attributes not supported by SCIM:

  • Profile picture
  • hand-signature
  • gender

User resources can not be deleted. Set users as inactive instead.


SCIM Documentation Link
(tick)GETRetrieve an existing resource (or list of resources)
(tick)POSTCreate a new resource
(tick)PUTUpdate an existing resource

Delete a resource

Some resources do not support deletion.
Some resource support deletion (Sherpany does a "soft-delete" on the server-side). Uniqueness constraints still apply.

Can't be deleted:

  • User
(minus)PATCHAtomic partial update

SCIM bulk operations are not supported.


Sherpany will setup the Organisation and configure SSO (SAML) with a whitelist of allowed email domains which will be under the jurisdiction of this SCIM Domain.


using a Bearer Token in the http header of all requests

Authorization: Bearer <TheToken>

The Token is bound to an Organisation and access is limited to Resources associated with that Organisation.

Sherpany Staff will provide the Token through a secure channel.

Advanced Token creation

It is also possible for the Sherpany Enterprise Customer to generate the RSA Keypair and use the Private key themselves to generate a RS512 JWT following our guidelines.

This has the benefit that:

  • the Secret Key never has to be communicated (only the public key needs to be sent to Sherpany)
  • the Customer can generate short lived tokens as needed which mitigates the risk of a token being stolen in-transit.


Get all users

Example Request to get all Users

GET /api/scim/Users HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbG.eyJvaWQiO.a7jxyB_kMcmi5

Create user

POST /api/scim/Users HTTP/1.1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer eyJhbG.eyJvaWQiO.a7jxyB_kMcmi5
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "",
  "externalId": "123",
  "name": {
    "givenName": "Test",
    "familyName": "Tester"
  "active": true

Update an existing user

PUT /api/scim/Users/965ffb27-6966-472d-a4b6-592bba3eeb82 HTTP/1.1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer eyJhbG.eyJvaWQiO.a7jxyB_kMcmi5
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "",
  "externalId": "123",
  "name": {
    "givenName": "Test",
    "familyName": "Tester II"
  "active": true

When to sync

It is recommended to sync individual Users right away when the changes happen. If that is not possible full sync can also be done periodically.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.