Account Management SCIM API 1.1

Overview

As people join and leave your organization, you need to grant and revoke access to Workplace. This set of guides introduces the concepts of account provisioning and deactivation through the use of the SCIM API. 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.

Using the Account Management API

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

API Access Token

Example

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

API Schemas

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

• urn:scim:schemas:core:1.0
• urn:scim:schemas:extension:enterprise:1.0
• urn:scim:schemas:extension:facebook:starttermdates:1.0
• urn:scim:schemas:extension:facebook:accountstatusdetails:1.0
• urn:scim:schemas:extension:facebook:auth_method:1.0
• urn:scim:schemas:extension:facebook:frontline:1.0

Core

The following properties belong to the core SCIM schema urn:scim:schemas:core:1.0

Enterprise

The following properties belong to the SCIM extension enterprise:1.0

Account Status Details

The following properties belong to the SCIM extension facebook:accountstatusdetails:1.0

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

unclaimed and invited account

claimed (with claimlink) account

unclaimed and not invited account

PUT:

update account from unclaimed to claimed

Request:

Response:

update account from claimed to unclaimed

Request:

Response:

update account from not invited to invited

You can use a PUT request to change the invited value from invited "false" to invited "true".

Request:

Response:

Frontline

The following properties belong to the SCIM extension facebook:frontline:1.0

The Frontline User Extension will allow you to include or exclude the user in the Frontline set of users. Set the value of the key "is_frontline" to either true or false.

GET Request

When retrieving the information of a user, the value of the "is_frontline" will be visible in case that your instance has the Frontline feature enabled.

POST Request

In the case where the Frontline feature set has been enabled in your instance, you can trigger a POST Request to create your user and put them in the Frontline people set.

PUT Request

In the case where the Frontline feature set has been enabled in your instance, you can trigger a PUT Request to include or exclude your user from the Frontline people set.

Authentication Method

The following properties belong to the SCIM extension facebook:auth_method:1.0

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 "auth_method" will be visible in case that you're instance has hybrid authentication enabled.

Single Sign On:

Username / 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 "auth_method" to "sso" or "password". In this case, the created user will only be able to log in with the configured "auth_method".

PUT Request

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

Start/Term Date

The following properties belong to the SCIM extension facebook:starttermdates:1.0

Data Structures

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.

Manager Data Structure

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

API Endpoints

The base URL for the Account Management API is:

Below are the edges which can be used for various operations.

EmailLess Examples

Create accounts without email addresses

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.

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:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:facebook:auth_method:1.0"
      ],
      "externalId": "1745847",
      "name": {
      "formatted": "Julius Caesar"
      },
      "active": true,
      "urn:scim:schemas:extension:facebook:auth_method:1.0": {
      "auth_method": "password"
      }
      }
    

The response in this case would look like this:

      {
      "schemas": [
      "urn:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:enterprise:1.0",
      "urn:scim:schemas:extension:facebook:starttermdates:1.0",
      "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0",
      "urn:scim:schemas:extension:facebook:auth_method:1.0"
      ],
      "id": 100024833978801,
      "externalId": "1745847",
      "name": {
      "formatted": "Julius Caesar"
      },
      "active": true,
      "urn:scim:schemas:extension:facebook:starttermdates:1.0": {
      "startDate": 0,
      "termDate": 0
      },
      "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
      "accessCode": "dwsngnlinocitezt",
      "accessCodeExpirationDate": 1528384514,
      "claimed": false,
      "invited": true,
      "inviteDate": 1520608512
      },
      "urn:scim:schemas:extension:facebook:auth_method:1.0": {
      "auth_method": "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:scim:schemas:core:1.0",
      "urn:scim:schemas:extension:enterprise:1.0",
      "urn:scim:schemas:extension:facebook:starttermdates:1.0",
      "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0",
      "urn:scim:schemas:extension:facebook:auth_method:1.0"
      ],
      "id": 100024833978801,
      "externalId": "1745847",
      "userName": "Julius.C",
      "name": {
      "formatted": "Julius Caesar"
      },
      "active": true,
      "urn:scim:schemas:extension:facebook:starttermdates:1.0": {
      "startDate": 0,
      "termDate": 0
      },
      "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
      "accessCode": "bcbegjpagzeqkwox",
      "accessCodeExpirationDate": 1528385241,
      "claimed": true,
      "claimDate": 1520609227,
      "invited": true,
      "inviteDate": 1520608512
      },
      "urn:scim:schemas:extension:facebook:auth_method:1.0": {
      "auth_method": "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.

auth_method needs to be "password"

It's not allowed to create an email less user with the auth_method set to "sso". We recommend that you add the "auth_method": "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 (in the case of a user without an email address)

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

• auth_method 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 DELETE request to delete users in case that those users didn't claim their account yet.

Deleting users that are already claimed

When you want to delete a user that claimed their account, you will need to do the following:

• Deactivate the account by using the "active: true" to "active: false" flag.
• Create a support ticket with the request to delete the account.
• Once the support team responds that you can delete the account, you will be able to run the DELETE Request.

People Sets Examples

endpoint supports Creating, Updating and Deleting peoplesets.

Get all People Sets

GET www.workplace.com/scim/v1
        /Groups

Get People Set

GET www.workplace.com/scim/v1
        /Groups/{peopleset-id}

Create People Set

Create a People set with members. The body must contain all member user IDs for a given people set.

POST www.workplace.com/scim/v1
        /Groups/

        {
        "schemas": [
        "urn:scim:schemas:core:1.0"
        ],
        "displayName": "Test People Set",
        "members": [
        {
        "type": "user",
        "value": {{user_id}}
        },
        {
        "type": "user",
        "value": {{user_id}}
        }
        ]
        }

Update People Set

Updates People set Name and/or members. The body must contain all member user IDs for a given people set.

PUT www.workplace.com/scim/v1
        /Groups/{peopleset-id}

        {
        "schemas": [
        "urn:scim:schemas:core:1.0"
        ],
        "displayName": "New Set Name",
        "members": [
        {
        "type": "user",
        "value": {{user_id}}
        },
        {
        "type": "user",
        "value": {{user_id}}
        }
        ]
        }

Delete People Set

DELETE www.workplace.com/scim/v1
        /Groups/{peopleset-id}

User Examples

Creating User Account

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

• Send a POST request to the endpoint https://www.workplace.com/scim/v1/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
• You should store each person's Workplace ID in a database for later use in 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:
• Make a GET request using the username filter to retrieve the existing user
• Merge your local user record with the existing Workplace user record
• 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

Add/Remove 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 profile picture

Get All Users

You can retrieve the information about your users:

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

GET /scim/v1/Users?count=10&startIndex=20 HTTP/1.1
Host: www.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

Get User by ID

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

GET /scim/v1/Users/{Workplace-assigned user id} HTTP/1.1
Host: www.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.”

Get User by Username

You can retrieve a single user by username / email address by including a userName filter. Please note that email address should be URL encoded as shown below.

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

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

Get User by ExternalId

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

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

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

Set Manager ID

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 or a PUT 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.

Update 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 request to the endpoint https://www.workplace.com/scim/v1/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

Deactivate User 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 request to the endpoint https://www.workplace.com/scim/v1/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.

Delete User Account

If a person's account has been created in error and that account has never been claimed by the user you can delete it.

1. Send a DELETE request to the endpoint https://www.workplace.com/scim/v1/Users/{Workplace-assigned user id}
2. Upon success, you will receive a 200 - OK response
3. If the account has ever been claimed, you will receive a 412 - Precondition Failed response

Deleting users that are already claimed

When you want to delete a user that claimed their account, you will need to do the following:

• Deactivate the account by using the "active: true" to "active: false" flag.
• Create a support ticket with the request to delete the account.
• Once the support team responds that you can delete the account, you will be able to run the DELETE Request.

Create Manager user

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

{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0"
],
"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:scim:schemas:extension:enterprise:1.0": {
"department": "Headquarters"
}
}

Read Manager's ID

{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0"
],
"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:scim:schemas:extension:enterprise:1.0": {
"department": "Headquarters"
}
}

Create User With Manager

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

{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:enterprise:1.0"
],
"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:scim:schemas:extension:enterprise:1.0": {
"department": "Senate",
"manager": {
"managerId": 11111111111
}
}
}

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