Account Management SCIM 2.0 API

Overview

As people join and leave your organization, you need to grant and revoke access to Workplace. This guide describes account provisioning and deactivation through the use of the SCIM API 2.0. This set of API calls will allow you to build a custom connector to provision and deactivate your people who are stored on your user directory.

On this page:

• Using the SCIM 2.0 API
• API Reference
• Accounts Without Email Addresses
• Usage Examples
• Upgrading from SCIM 1.1 API

Using SCIM 2.0 API

The SCIM 2.0 Account Management API for Workplace is a SCIM-compliant REST API. The SCIM specification was designed to easily manage user identities and grouping in cloud-based apps and services.

API Access Token

This API will only process requests that include a valid access token, which you must send as an authorization header when making API calls.

To receive an access token, you need to create an app on the Integrations page of the Admin Panel. More information can be found in the Apps and Permissions documentation.

The Manage Accounts permission is required to allow SCIM API access.

Example API Call

As a basic example, the below is a minimal API call to fetch a list of users from the /Users endpoint, including an access token and user agent.

GET /Users/ HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}
User-Agent: {your user agent}

API Reference

The User Management API data structure is comprised of the core User SCIM schema and several schema extensions:

• 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:facebook:accountstatusdetails:2.0:User
• urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User
• urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User
• urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User

The Group Management API data structure is comprised of the core Group SCIM schema:

• urn:ietf:params:scim:schemas:core:2.0:Group

Core User Schema

The following properties belong to the core SCIM schema urn:ietf:params:scim:schemas:core:2.0:User

Enterprise User Extension

The following properties belong to the SCIM extension urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Account Status Details Extension

The following properties belong to the SCIM extension urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User

Depending on whether a user is created, invited or claimed the account, the field values within the account status details will appear or change.

GET:

unclaimed and deactivated account

"urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
      "claimed": false,
      "invited": false,
      "inviteDate": "2017-05-19T13:14:29+00:00"
}

invited and unclaimed account

"urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": false,
    "invited": false,
    "inviteDate": "2017-05-19T13:14:29+00:00"
}

claimed (via claimlink) account

"urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": true,
    "claimDate": "2017-05-22T10:34:35+00:00",
    "invited": true,
    "inviteDate": "2017-05-19T13:14:29+00:00"
}

not invited and unclaimed account

"urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": false,
    "invited": false
}

PUT and PATCH:

update account from not invited to invited

You can use a PUT or PATCH request to trigger unsent user invites. Read only attributes can be omitted.

Request:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
    "claimed": false,
    "invited": true
}

Response:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
    "claimed": false,
    "claimLink": "<claimLink url>",
    "invited": true,
    "inviteDate": "2017-05-19T13:14:29+00:00"
}

update account from claimed to unclaimed

You can use a PUT or PATCH request to reset the claimed status of an account. Read only attributes can be omitted.

Request:

"urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": false,
    "invited": true,
}

Response:

"urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": false,
    "claimLink": "<claimLink url>",
    "invited": true,
    "inviteDate": "2017-05-19T13:14:29+00:00"
    }

Authentication Method Extension

The following properties belong to the SCIM extension urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User

The Authentication Method Extension will allow you to set the authentication method in case that you've enabled the possibility to log in with either "sso" or "password".

GET Request

When retrieving the information of a user, the value of the "authMethod" will be visible in case that your instance has hybrid authentication enabled.

Single Sign On:

"urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
    "authMethod": "sso"
}

Username / Password:

"urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
    "authMethod": "password"
}

POST Request

In case the hybrid authentication is enabled for your instance, you can trigger a POST Request to create your users and set the "authMethod" to "sso" or "password". In this case, the created user will only be able to log in with the configured "authMethod".

PUT and PATCH Request

In case hybrid authentication is enabled for your instance, you can trigger a PUT or PATCH Request to update the "authMethod" of your users and change the "authMethod" to "sso" or "password".

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "path": "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User:authMethod ",
            "value": "sso"
        }
    ]
}

Frontline Extension

The following properties belong to the SCIM extension urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User

The Frontline Extension will allow you to set which accounts are for frontline team members and to toggle account access to meet local regulatory responsibilities.

PUT and PATCH Request

Frontline status of a user and their access can be toggled after creation.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "path": "urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User:frontline",
            "value": true
        },
        {
            "op": "replace",
            "path": "urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User:hasAccess",
            "value": false
        }
    ]
}

Start / Termination Date Extension

The following properties belong to the SCIM extension urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User

Custom Profile Fields Extension

The Additional Profile Fields product feature allows Workplace customers to enable additional profile fields, which are optional, in their organization and use them for use cases including Auto Group Membership. These additional fields profile fields can be controlled by community admins just like default profile fields, from the Admin Panel Profile Fields settings page.

Before using any of the Additional Profile Fields with SCIM 2.0 API in a community, they have to be added to that community using the above setup instructions and the Additional Profile Fields should be editable by IDP Integrations.

Note:

The following properties belong to the SCIM extension urn:ietf:params:scim:schemas:extension:customprofilefields:2.0:User

FixedTextField Data Structure

Name Mapping for Custom Profile Fields

A selection of additional profile fields are available for system admins to enable in their company. The table below lists all the available fields and their API names to be used in SCIM API requests to update Workplace user profiles.

Usage Examples

GET

In a company which has enabled additional profile fields and for a user who has an additional profile field set.

Note: Additional profile fields are not sent in response by default and have to be explicitly requested in a GET request

Request:

GET /Users/100069996612677?attributes=meta,active,locale,emails,userName,name,profileUrl,id,schemas,urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User:frontline,urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:inviteDate,urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:invited,urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:claimed,urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:canDelete,urn:ietf:params:scim:schemas:extension:facebook:authMethod:2.0:User:authMethod,urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User:fixedTextFields
Host: scim.workplace.com
Authorization: Bearer ${BEARER_TOKEN}

Response:

...
"urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User": {
    "fixedTextFields": [
      {
        "type": "work_schedule",
        "value": "Part Time"
      },
      {
        "type": "store",
        "value": "703452"
      }
    ],
   },
"profileUrl": "",
"profileUrl": true,
"urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
    "authMethod": "password"
}
...
    

POST

Creating a user using Workplace SCIM v2 API with custom profile fields.

POST /Users
Host: scim.workplace.com
Authorization: Bearer {your access token}
Content-Type: application/json

{
  "active":true,
  "userName":"user1@company1.com",
  "name": {
    "formatted" : "SCIM Coworker 1"
  },
  "urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User":{
    "fixedTextFields": [
      {
        "type": "work_schedule",
        "value": "Full time"
      },
      {
        "type": "employee_type",
        "value": "Regular"
      }
    ]
  }
}

PUT

Updating a user profile using Workplace SCIM v2 API with custom profile fields

PUT /Users/:user_id'
Host: scim.workplace.com
Authorization: Bearer {your access token}
Content-Type: application/json


{
  ...      
  "urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User":{
    "fixedTextFields": [
      {
        "type": "work_schedule",
        "value": "Full time"
      },
      {
        "type": "employee_type",
        "value": "Regular"
      }
    ]
  }
  ...
}

PATCH without path

Patching a user profile without path parameter using Workplace SCIM v2 API

Note: PATCH request type supports updating additional profile fields. Along with updating other user profile fields like name or addresses or locale, Workplace SCIM PATCH API for Users can be used to update one or more Additional Profile Fields as well in the same request without sending in the path parameter in the req body.

PATCH /Users/:user_id
Host: scim.workplace.com
Authorization: Bearer {your access token}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "value": {
      "urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User": {
        "fixedTextFields": [{
          "type": "work_schedule",
          "value": "Part time"
        },{
          "type": "employee_type",
          "value": "Seasonal"
        }]
      }
    }
  }]
}

Delete an Additional Profile Field using PATCH without path:

Sending a null value to an additional profile field would delete the field from a user’s profile.

PATCH /Users/:user_id
Host: scim.workplace.com
Authorization: Bearer {your access token}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "value": {
      "urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User": {
        "fixedTextFields": [{
          "type": "work_schedule",
          "value": null
        },{
          "type": "employee_type",
          "value": null
        }]
      }    
    }
  }]
}

PATCH with path and without filter:

Patching a user profile with path parameter using Workplace SCIM v2 API.

Note: PATCH request type supports updating additional profile fields. Workplace SCIM PATCH API for Users can be used to update one or more Additional Profile Fields as well in the same request by sending in the path parameter to the customprofilefields schema extension.

PATCH /Users/:user_id'
Host: scim.workplace.com
Authorization: Bearer ${your access token}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "path": "urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User:fixedTextFields",
    "value": [{
      "type":"work_schedule",
      "value":"Seasonal"
    }]
  }]
}

PATCH with path and filter:

Patching a user profile with path and filter parameter using Workplace SCIM v2 API

Note: PATCH request type supports updating additional profile fields. Workplace SCIM PATCH API for Users can be used to update a particular Additional Profile Fields by sending in the path parameter with a filter specifying the exact additional profile field to the customprofilefields schema extension.

PATCH /Users/:user_id
Host: scim.workplace.com
Authorization: Bearer {your access token}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "replace",
    "path": "urn:ietf:params:scim:schemas:extension:facebook:customprofilefields:2.0:User:fixedTextFields[type eq \"work_schedule\"].value",
    "value": "Seasonal Term"
  }]
}

Name Data Structure

The following fields make up the Name data structure used by the name field.

Email Data Structure

The following describes the data structure used by the email field.

Address Data Structure

The following describes the data structure used by the address field.

User Reference Data Structure

The following describes the data structure used by the user reference fields, e.g manager, members.

Core Group Schema

The following properties belong to the core SCIM schema urn:ietf:params:scim:schemas:core:2.0:Group

Within Workplace SCIM Groups are mapped to People Sets. Users should only be added to and removed from groups, never updated.

create a SCIM group via POST

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "externalId": "<external id>",
    "displayName": "<group name>"
}

You can use a PATCH request to add or remove members from a group as well change the display name.

add a user to a SCIM group

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "members",
            "value": [
                {
                    "value": "<user id>"
                }
            ]
        }
    ]
}

remove a user from a SCIM group

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "remove",
            "path": "members[value eq \"<user id>\"]"
        }
    ]
}

Create accounts without email addresses (beta only)

We now allow for users to be created without the need for an actual email address. In order to do this, you will need to create a user that has an external id and a formatted name. You can still choose to add other attributes in case you want to add a user with rich profile data.

How can I create and update a user without an email address?

In order to create an email less user, you'll need to create a user that has at least the following parameters:

• externalId
• formatted name

The request could look like the following:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User"
    ],
    "externalId": "1745847",
    "name": {
        "formatted": "Julius Caesar"
    },
    "active": true,
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
        "authMethod": "password"
    }
}

The response in this case would look like this:

{
    "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:facebook:accountstatusdetails:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User"
    ],
    "id": "100024833978801",
    "externalId": "1745847",
    "name": {
        "formatted": "Julius Caesar"
    },
    "active": true,
    "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
        "accessCode": "dwsngnlinocitezt",
        "accessCodeExpirationDate": "2017-05-22T10:34:35+00:00",
        "claimed": false,
        "invited": true,
        "inviteDate": "2017-05-19T13:14:29+00:00"
    },
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
        "authMethod": "password"
    }
}

It's important to know that the response won't create a username yet. The username will only be set once the user activates the account by using the access code on the desktop or mobile applications.

Once the user activated the account, you will get the following response:

{
    "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:facebook:accountstatusdetails:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User"
    ],
    "id": "100024833978801",
    "externalId": "1745847",
    "userName": "Julius.C",
    "name": {
        "formatted": "Julius Caesar"
    },
    "active": true,
    "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
        "accessCode": "bcbegjpagzeqkwox",
        "accessCodeExpirationDate": "2017-05-22T10:34:35+00:00",
        "claimed": true,
        "claimDate": "2017-05-20T09:44:18+00:00",
        "invited": true,
        "inviteDate": "2017-05-19T13:14:29+00:00"
    },
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
        "authMethod": "password"
    }
}

When the account is activated, you'll notice two things:

• The username is visible
• The access code has changed

Because of the fact that the username is now set, we can use an access code to reset the password of this user based on a username and access code.

authMethod needs to be "password"

It's not allowed to create an email-less user with the authMethod set to "sso". We recommend that you add the "authMethod": "password" to all of the POST and PUT requests to avoid any errors in case the default authentication is set to "sso"

{
    "Errors": [
        {
            "description": "People without email have to use a password to log in: Select 'Password' for this users login method",
            "code": 1855128
        }
    ]
}

When you want to update a user, you can update any value apart from the following parameters:

Error message will be triggered when updating

• username

{
    "Errors": [
        {
            "description": "You Can't Change Your Username: Usernames are permanent and can't be changed.",
            "code": 1855129
        }
    ]
}

• authMethod to "sso"

{
    "Errors": [
        {
            "description": "You Can't Change Your Username: Usernames are permanent and can't be changed.",
            "code": 1855129
        }
    ]
}

• accessCode
• accessCodeExpirationDate

When you try to change the values for these parameters, the original value will be returned.

How can I retrieve my email-less users?

You can use the GET request in the same way that you would use the GET request for users with an email address. The only difference is that you will only be able to see a username in case the user claimed the account.

How can I delete or deactivate my email less users?

You can use the PUT and PATCH requests to deactivate user accounts. The Workplace SCIM 2.0 API has not enabled support for deleting user accounts.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "path": "active",
            "value": false
        }
    ]
}

Usage Examples

Creating an Account for a Person

When a new person joins your organization or is newly-granted access to Workplace, you must create an account for them.

To create a new account, send a POST request to the endpoint https://scim.workplace.com/Users/.

Upon success, you will receive a 201 - Created response. The response body will contain a JSON representation of the person's account, including the Workplace-assigned ID, which must be used to do any subsequent update operations.

If a user already exists within your Workplace instance with the same username, you will receive a 409 - Conflict response.

The typical recovery path for a conflict is to:

1. Make a GET request using the username filter to retrieve the existing user.
2. Merge your local user record with the existing Workplace user record.
3. Do a PUT operation to update the Workplace user.

You may receive another response code - refer to the error codes section below for more details.

Create a User with a Profile Picture

You can create a user and set their initial Workplace profile picture if you have an internet-accessible image URL for the person by including the photos attribute with the type set to profile and primary set to true.

"photos": [
    {
        "value": "http://www.example.com/julius_profile_pic.jpeg",
        "type": "profile",
        "primary": true
    }
]

Remove the profile picture that was set through the API

Getting All Users

You can retrieve the information about your users:

• Send a GET request to the endpoint https://scim.workplace.com/Users
• By default, a GET request on /Users will return results in pages of 100.
• You can specify a different page size and page offset by including the parameters count and startIndex.

GET /Users?count=10&startIndex=20 HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}

Upon success:

• You will receive a 200 - OK response
• The response body will contain a JSON representation of the requested users

Getting one user by ID

You can retrieve a single user by the user's Workplace ID:

GET /Users/{Workplace-assigned user id} HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}

If a user doesn't exist:

• You will receive a 404 - OK response
• Error message: “User or Group Not Available: The user or group you tried to access from SCIM is not available.”

Getting one User by Username

You can retrieve a single user by username / email address by including a username filter:

GET /Users?filter=userName%20eq%20%22juliusc@example.com%22 HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}

If no user exists with that username, you will receive an empty response list.

Getting one User by External Id

You can retrieve a single user by their external id by including a username filter:

GET /Users?filter=externalId%20eq%20%22{external-id}%22 HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}

If no user exists with that externalId, you will receive an empty response list.

Setting Manager IDs

Workplace recommends always setting manager IDs for your users, since it creates a better user experience for the people using the product.

1. You can set a user's manager during either a POST, PUT or PATCH operation, but doing so requires having the Workplace-assigned user ID for the manager.
2. When doing create operations, you may not yet have the manager's user ID when you create the user.
3. To simplify this, use two-pass logic (explained below) to create users and then set manager IDs.

Two-pass Logic

On the first pass:

1. Iterate over each user
2. Build the request payload, but do not set the manager relationship
3. Simply create each user by sending a POST request
4. Store each created-users' IDs in a data store

After users have been created, do a second pass to update each user's manager:

1. Iterate over each user
2. Lookup the user's manager's Workplace user ID in your data store
3. Create the request payload for this user, adding the manager's ID to the request body
4. Finally send a PUT request to Workplace to update the user and set the manager relationship

Updating a User

When any user attribute changes in your user directory, you must update the user's account in Workplace. This can either be done on event, when the underlying data changes, or in a batch, say every 3 hours. In either case, the logic is the same:

1. Prepare the request body with the updated data.
2. Send a PUT or PATCH request to the endpoint https://scim.workplace.com/Users/{Workplace-assigned user id}
3. Upon success, you will receive a 200 - OK response
4. If the user id you specified does not exist, you will receive a 404 - Not Found response

Deactivating a User's Account

When a person leaves your organization or should not longer have access to Workplace, you must deactivate their account:

1. Generate the request body setting the attribute active to false.
2. Send a PUT or PATCH request to the endpoint https://scim.workplace.com/Users/{Workplace-assigned user id}
3. Upon success, you will receive a 200 - OK response. The user will immediately be deactivated and any current mobile or web sessions for that user will be immediately terminated.

Deleting a User Account

Further Examples

Create a Person Who is a Manager

POST /Users/ HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    ],
    "userName": "juliusc@example.com",
    "name": {
        "formatted": "Julius Caesar"
    },
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "juliusc@example.com"
        }
    ],
    "addresses": [
        {
            "type": "work",
            "formatted": "Emporer's Palace",
            "primary": true
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Headquarters"
    }
}

Read the Manager's ID From the Response Body

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    ],
    "id": "11111111111",
    "userName": "juliusc@example.com",
    "name": {
        "formatted": "Julius Caesar"
    },
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "juliusc@example.com"
        }
    ],
    "addresses": [
        {
            "type": "work",
            "formatted": "Foro Italico",
            "primary": true
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Headquarters"
    }
}

Create a Person With an Assigned Manager

POST /Users/ HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    ],
    "userName": "marka@example.com",
    "name": {
        "formatted": "Mark Antony"
    },
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "marka@example.com"
        }
    ],
    "addresses": [
        {
            "type": "work",
            "formatted": "Foro Italico",
            "primary": true
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Senate",
        "manager": {
            "value": "11111111111"
        }
    }
}

Upgrading from SCIM v1.1

Workplace has deprecated SCIM v1.1 support and will require migration of all accounts to SCIM v2.0 by Oct 2022.

SCIM v2.0 is the latest standard for Cross-domain Identity Management, it builds on top of the v1.1 specification adding PATCH operations to facilitate management of users and groups at a scale far beyond the practical limitations of SCIM v1.1.

The key differences between the v1.1 and v2.0 specifications are outlined below, along with the changes to Workplace extension schemas.

Paths

Schemas

urn:scim:schemas:core:1.0 vs urn:ietf:params:scim:schemas:core:2.0:User

New Read Only Attributes have been added.

urn:scim:schemas:extension:enterprise:1.0 vs urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Manager Data Type has been updated to match the SCIM v2.0 Multi-Valued Attribute structure.

urn:scim:schemas:extension:facebook:accountstatusdetails:1.0 vs urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User

Date attributes have been updated from an Integer type representing an epoch timestamp, to the SCIM v2.0 DateTime type, which is a W3C data formatted string (xsd:dateTime).

urn:scim:schemas:extension:facebook:auth_method:1.0 vs urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User

Attribute names updated to match SCIM v2.0 naming convention.

urn:scim:schemas:extension:facebook:frontline:1.0 vs urn:ietf:params:scim:schemas:extension:facebook:frontline:2.0:User

Attribute names updated to match SCIM v2.0 naming convention. New Workplace specific hasAccess attribute.

urn:scim:schemas:extension:facebook:starttermdates:1.0 vs urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User

Date attributes have been updated from an Integer type representing an epoch timestamp, to the SCIM DateTime type, which is a W3C data formatted string (xsd:dateTime).

urn:ietf:params:scim:schemas:core:2.0:Group

New Read Only Attributes have been added.

PATCH

PATCH operations are a new addition in SCIM v2.0 and thus no migration is required, their use is recommended.

PATCH operations allow update payloads to be reduced to only the attributes being updated. This reduces the payload size and avoids accidental overwriting of attributes with out of date values.

Use of PATCH operations is essential for effective group management at scale.

PATCH requests can make one or more update operations to the specified resource in a single request. Allowed operations are: add, replace and remove. The value property is not required for a remove operation. Filtering of multi-value attributes can be achiveved with filtering syntax in the path, see the remove user from group example above.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "add",
            "path": "members",
            "value": [
                {
                    "value": "111111111111"
                }
            ]
        },
    ... + additional operations if needed ...
    ]
}