SCIM 2.0

SCIM is a widely accepted open standard designed to make managing user identities and user groups easier in cloud-based applications and services. It has a set of default contracts for users and groups which can be extended.

Our SCIM implementation targets version 2.0 of the protocol. Useful links:

This article covers SCIM implementation in Showpad.

Prerequisites

Showpad Enterprise package
Showpad admin account
A third-party identity management system

You should consider SCIM implementation as an extension of the Showpad API. Access can be done via Bearer authentication.

Base Endpoint

The base endpoint for SCIM calls is:

https://{{subdomain}}.showpad.biz/api/users/scim/v2

Every request needs to be prefixed with the base endpoint.

Mapping

User maps SCIM attributes to a Showpad User. You can list, filter, add, edit or remove users.

A new user will be automatically assigned to the "All Users" group. This is a default group that you can't unassign from the user. If you want to assign the user to another group, it should exist already or be created via the groups endpoint.

SCIM attribute	Showpad Field	Attribute Type	Required	Default
`ID`	`id`	Singular	True
`userName`	`userName`	Singular	True
`name.givenName`	`firstName`	Singular	True
`name.familyName`	`lastName`	Singular	True
`emails[0].value`	`email`	Singular	True
`active`	`isActive`	Singular	False
`timezone`	`timezone`	Singular	False
`locale`	`language`	Singular	False	en
`title`	`companyRole`	Singular	False	""
`externalID`	`scimId`	Singular	False	""
`enterprise.organization`	`companyName`	Singular	False	Current organization
`phoneNumbers[0].value`	`phone`	Singular	False	""
`phoneNumbers[0].type`	--	Singular	False	"work" (read-only)
`emails[0].type`	--	Singular	False	"work" (read-only)
`emails[0].primary`	--	Singular	False	True (read-only)
`roles[0].value`	`userType`	Singular	False	"tablet"
`groups`	`usergroups`	Multi-Valued	False	"All users" group
`groups.value`	`usergroups.id`	Singular	False	"All users" group ID
`groups.display`	`usergroups.name`	Singular	False	"All users"
`entitlements`	`managedUsergroups`	Multi-Valued	False
`entitlements.type`	--	Singular	False
`entitlements.value`	`managedUsergroups.id`	Singular	False
`manager.value`	`managerId`	Singular	False

Attributes

User

User attributes are multi-valued in SCIM but singular in Showpad. When you're creating or replacing the user and specify multiple values, the primary value will be mapped and the other values discarded. If there is no primary, the first value will be used.

Attribute	Description
`phoneNumbers`
`emails`
`roles`	A means of grouping users with similar permissions, each group of users has access to the information intended for them according to rules that have been pre-defined by an administrator. When changing this value, be aware that only certain roles are supported: owner - Only 1 owner is allowed. You will get a `uniqueness` error if you try to create another one. admin manager - When a user has the `manager` role, they can have groups assigned for which they can coach other users. Assigning these groups can happen via the `entitlements` section. A single manager can have multiple entitlements assigned to them. Note: this is the only entitlement currently supported. tablet - This is a default role.
`groups`	Read-only attribute. This allows you to see to which user groups a user belongs. Modifying a user's membership to a group should be handled through the `Usergroup` resource.
`enterprise`	In the table corresponds to enterprise schema `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`
`emails[0].value`	Should follow email pattern. Must be unique in the system. Otherwise you will get an `uniqueness`error.
`username`	This must be unique in the system, otherwise you'll get a `uniqueness`error.
`manager.value`	This value should be either the Showpad ID or the email address of an existing Showpad user.

Entitlements

When a user has the manager role, they can have groups assigned for which they can coach other users. Assigning these groups can happen via the entitlementssection using:

"entitlements": [
    {
        "value": "22b3d7f8eea74c37d3d140642ccbaeba",
        "type": "coach_for_group"
    }
]

Groups

SCIM attribute	Showpad field	Attribute Type	Required
`ID`	`id`	Singular	True
`displayName`	`name`	Singular	True
`members`	`users`	Multi-Valued	False
`members.value`	`users.id`	Singular	False
`members.display`	`users.username`	Singular	False

Pagination

You can paginate through results by using startIndex and count query parameters.

For example, the following code will output the second page of a 10-paged result:

User

/Users?startIndex=11&count=10

Groups

/Groups?startIndex=11&count=10

Filtering

You can filter for users by fields following the specs. Currently, only the EQ operator on username is supported.

User

The following code will result in a list of users whose username is "john.doe@showpad.com":

/Users?filter=username%20eq%20"john.doe@showpad.com"

Groups

Filtering for groups has not been implemented in Showpad's SCIM 2.0 version.

POST

Users

This command creates a user.

POST {{url}}/Users
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
  "active": true,
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "john.doe@showpad.com"
    }
  ],
  "locale": "en",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "entitlements": [
    {
        "value": "22b3d7f8eea74c37d3d140642ccbaeba",
        "type": "coach_for_group"
    }
  ],
  "roles": [
    {
      "value": "manager"
    }
  ],
  "timezone": "Europe/Brussels",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "organization": "John Doe's org"
  },
  "userName": "john.doe@showpad.com"
}

Groups

This command creates a group.

POST {{url}}/Groups
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "SCIM test group",
  "members": [
    {
      "value": "abcdefgh123456789"
    },
    {
      "value": "123456789abcdefgh"
    }
  ]
}

GET

Schemas

Using a GET request you can retrieve:

Endpoint	Description
`/Schemas`	Retrieves all configuration details.
`/Schemas/urn:ietf:params:scim:schemas:core:2.0:User`	Retrieves user configuration details.
`/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group`	Retrieves group configuration details.
`/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`

ResourceTypes

Using a GET request you can retrieve:

Endpoint	Description
`/ResourceTypes`	Outputs types of resources.
`/ResourceTypes/User`
`/ResourceTypes/Group`

ServiceProviderConfig

Using a GET request you can retrieve:

Endpoint	Description
`/ServiceProviderConfig`	Returns a list of operations supported in the current implementation.

Users

This command returns a list of users, at 100 per page by default. You can adjust the results by sing pagination and/or filtering.

GET {{url}}/Users?startIndex=11&count=10&filter=username%20eq%20%22john.doe@showpad.com%22
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

Users/{Id}

This command returns a user with the specified ID.

GET {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

Groups

This command returns a list of groups, 100 groups per page by default. You can adjust the results by using pagination.

GET {{url}}/Groups?startIndex=11&count=10"
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

Groups{id}

This command returns a group with a specified ID.

GET {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

PUT

Users/{id}

This command updates a user.

PUT {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
  "emails": [
    {
      "value": "john.doe.second@showpad.com"
    }
  ],
  "name": {
    "familyName": "Doe Second",
    "givenName": "John"
  },
  "userName": "john-doe-second"
}

Groups/{id}

This command updates a group.

PUT {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "SCIM test group change",
  "members": [
    {
      "value": "abcdefgh123456789"
    },
    {
      "value": "123456789abcdefgh"
    }
  ]
}

DELETE

Users/{id}

This command deletes a specific user.

DELETE {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

A 204 No Content response will be returned in the case of a successful deletion.

Groups/{id}

This command deletes a specific group.

DELETE {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

A 204 No Content response will be returned in the case of a successful deletion.

PATCH

This feature has not been implemented in Showpad's SCIM 2.0 version.

Base Endpoint​

Mapping​

Attributes​

User​

Entitlements​

Groups​

Pagination​

User​

Groups​

Filtering​

User​

Groups​

POST​

Users​

Groups​

GET​

Schemas​

ResourceTypes​

ServiceProviderConfig​

Users​

Users/{Id}​

Groups​

Groups{id}​

PUT​

Users/{id}​

Groups/{id}​

DELETE​

Users/{id}​

Groups/{id}​

PATCH​

Base Endpoint

Mapping

Attributes

User

Entitlements

Groups

Pagination

User

Groups

Filtering

User

Groups

POST

Users

Groups

GET

Schemas

ResourceTypes

ServiceProviderConfig

Users

Users/{Id}

Groups

Groups{id}

PUT

Users/{id}

Groups/{id}

DELETE

Users/{id}

Groups/{id}

PATCH