User Provisioning with 8x8 SCIM API

Updated: 04/23/2024

Objective

Provide an overview of 8x8’s SCIM API for user provisioning with the System for Cross domain Identity Management (SCIM) 2.0 industry standards.

Applies To

  • 8x8 Work
  • User Provisioning
  • SCIM API

Procedure

Planning Your SCIM Integration

There are two approaches to integrating user provisioning via SCIM:
  1. Using a pre-built integration with either Microsoft Azure AD or Okta. For more information on setting up these integrations see:
  2. Custom integration directly with the SCIM API
This article is mainly concerned with the second option.

Obtain an 8x8 API Token

Calls to the 8x8 SCIM API must include an http Authentication header containing an authentication token.
An authentication token may be obtained from Admin Console as follows:
  1. Log in to Admin Console.
  2. From Home, click on Identity and Security.
    tempsnipEDIT.png
  3. In the User Provisioning Integration (SCIM) section, select Other SCIM Provider and copy both the 8x8 URL and 8x8 API Token into the properties of your SCIM provider.
    tempsnipEDIT2.png
Note: If you are already using a user provisioning integration with an external Identity Provider, then you can re-use the API URL and authentication token for your native SCIM integration client for GET operations only. We do not support the use of multiple clients for POST/PATCH/PUT/DELETE operations.

8x8 SCIM API

The following CRUD operations are supported with 8x8 SCIM APIs:
  • Create Users
  • Get Users
  • Get User By User ID
  • Update Users
  • Deactivate Users
  • Activate Users
Note: Deletion of a user is not supported. The SCIM DELETE operation will result in the user being deactivated.

Modifiable User Attributes

Attributes are the details or fields associated with a user. The table below lists supported attributes, their SCIM schema and any applicable restrictions.
SCIM Attribute
SCIM Schema
Admin Console User Field
Restrictions
name.givenName
User
First name
Mandatory
name.familyName
User
Last name
Mandatory
userName
User
User name¹
Mandatory
Must be unique across all 8x8
emails [work]
User
Email address
Mandatory
Only one email address is supported.
Primary sub-attribute is ignored and is always true.
Defaults to noreply@8x8.com if omitted.
externalId
User
n/a
Optional
phoneNumbers [mobile]
User
Personal contact number
Optional
Primary sub-attribute is ignored and is always true.
phoneNumbers [work]
User
Personal contact number (not visible in Admin Console)
Optional
Primary flag is ignored and always false for provided work numbers
title
User
Job title
Optional
locale
User
Language
Optional
Language tags must be from the  ISO639-1 set
Default = inherited from site or en-US if not set
timezone
User
Time zone
Optional
Default = inherited from site or not set if site is not set
active
User
Active/Inactive²
Optional
Default = false
department
Enterprise User
Department
Optional
site
8x8 User³
Site
Optional
Must match the name of a site configured in Admin Console
Cannot be modified once set
Notes:
  1. The userName attribute also sets the user’s Federation ID (used for Single Sign-On) on create only.
  2. Inactive users are shown as a grayed out row in Admin Console.
  3. 8x8 User schema URN is urn:ietf:params:scim:schemas:extension:8x8:1.1:User.

Read-Only User Attributes 

The table below lists attributes that may be returned when retrieving a user but cannot be set or modified via SCIM.
SCIM Attribute
SCIM Schema
Admin Console User Field
Restrictions
phoneNumbers [work][primary=true]
User
Phone numbers
Extension DID has primary sub-attribute set to true.
Present only if user is assigned an X Series license
Read-only (set from Admin Console)
extension 8x8 User¹ Extension number
Present only if user is assigned an X Series license

Read-only (set from Admin Console)
Notes: 
  1. 8x8 User schema URN is urn:ietf:params:scim:schemas:extension:8x8:1.1:User

Get All Users

Gets a list of all users in the company. For pagination, specify numbers for startIndex and count.
Operation: GET
URL:
https://platform.8x8.com/udi/customers/<CUSTOMER_ID>/scim/v2/Users?startIndex=<X>&count=<Y>
Headers:
Authorization: Bearer <Access Token>
Content-Type: application/json
Body:
None

Get User By User ID

Gets a single user identified by User ID.
Operation: GET
URL:
https://platform.8x8.com/udi/customers/<CUSTOMER_ID>/scim/v2/Users/<USER_ID>
Headers:
Authorization: Bearer <Access Token>
Content-Type: application/json
Body:
None.

Create User

Creates a user. Must include userName, givenName, familyName and exactly one email address in order to create a user.
Operation: POST
URL:
https://platform.8x8.com/udi/customers/<CUSTOMER_ID>/scim/v2/Users
Headers:
Authorization: Bearer <Access Token>
Content-Type: application/json
Body:
 
{
  "userName": "jdoe",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "active": true,
  "locale": "en-US",
  "timezone": "US/Pacific",
  "emails": [
    {
      "value": "john@abc.com",
      "type": "work",
      "primary": true
    }
  ],
  "externalId": "1234",
  "phoneNumbers": [
    {
      "value": "+14085551234",
      "type": "work"
    },
    {
"value": "+14085551235",
      "type": "mobile"
    }
  ],
  "title": "Manager",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "billing"
  },
  "urn:ietf:params:scim:schemas:extension:8x8:1.1:User": {
    "site": "HQ"
  }
}

Update User

Updating a user results in the specified user profile property changes.  Note that a PUT operation must include all attributes, regardless of whether they are being modified or not.  
The absence of an attribute in a PUT body is processed as clearing those values, i.e., is equivalent to explicitly setting them to null or an empty array.
Refer to the table in the User Attributes section to see which attributes are mandatory and which optional attributes have a default if cleared.
Operation: PUT
URL:
https://platform.8x8.com/udi/customers/<CUSTOMER_ID>/scim/v2/Users/<USER_ID>
Headers:
Authorization: Bearer <Access Token>
Content-Type: application/json
Body:
{
  "userName": "jdale",
  "name": {
    "familyName": "Dale",
    "givenName": "John"
  },
  "active": true,
  "locale": "en-US",
  "timezone": "US/Pacific",
  "emails": [
    {
      "value": "john@abc.com",
      "type": "work",
      "primary": true
    }
  ],
  "externalId": "1234",
 "phoneNumbers": [
    {
      "value": "+14085551234",
      "type": "work"
    },
    
    {
      "value": "+14085551235",
      "type": "mobile"
    }
  ],
 
  "title": "Manager",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "billing"
  },
  "urn:ietf:params:scim:schemas:extension:8x8:1.1:User": {
    "site": "HQ"
  }
}

Deactivate User

Deactivation sets a user’s status from active to inactive. Deactivating a user results in the following end user experience for 8x8 services:
  • Login to 8x8 softphone (8x8 Work for Desktop/8x8 Work for Mobile) is not allowed.
  • From hardware device endpoints:
    • Inbound calls are allowed
    • Outbound PSTN calling is not allowed
    • Extension to extension calling is allowed
    • Only emergency calling is allowed
Updating a user results in the specified user profile property changes.
Operation: PATCH
URL:
https://platform.8x8.com/udi/customers/<CUSTOMER_ID>/scim/v2/Users/<USER_ID>
Headers:
Authorization: Bearer <Access Token>
Content-Type: application/json
Body:
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "active": false
      }
    }
  ]
}

Activate User

Activating a deactivated user profile will restore their 8x8 services.
Operation: PATCH
URL:
https://platform.8x8.com/udi/customers/<CUSTOMER_ID>/scim/v2/Users/<USER_ID>
Headers:
Authorization: Bearer <Access Token>
Content-Type: application/json
Body:
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": {
        "active": true
      }
    }
  ]
}

Additional Information

About SCIM 2.0

SCIM is designed to simplify user identity management in cloud-based applications, retaining secure authentication, authorization and privacy. 8x8’s SCIM API leverages these foundational SCIM capabilities and is geared towards facilitating rapid user onboarding using a common user schema and extensibility, thereby reducing the cost and complexity of administration.
SCIM is an open standard, see here for documentation.

Limitations

The SCIM API has some known limitations which are due to be addressed in a future release. See also the restrictions column in the User Attributes section of this document.
  • The API does not support:
    • Assignment of licenses, cost center or user profile
    • Setting of work phone number
    • Update to site once set
    • Setting of profile picture
  • Some fields set through the SCIM API can be subsequently modified in Admin Console. Depending on your SCIM implementation this may lead to some inconsistency between your Identity Management System and Admin Console
  • Modification of fields other than “active” is not supported with the PATCH operation. Use PUT instead.
  • The fields in 8x8 Admin Consoles for the users which are provisioned through SCIM API, are read only and can be changed only via the IdP.