User Provisioning with 8x8 SCIM API

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

Objective

To provision users with 8x8 SCIM API.

The objective of this document is to provide an overview of 8x8’s SCIM API for user provisioning, built using System for Cross domain Identity Management (SCIM) 2.0 industry standards.

Applies To

Users
Provisioning
SCIM API

Procedure

Getting Started

Please contact your Deployment representative for help obtaining an authentication token and the URL of the API.

Calls into the 8x8 SCIM API must include an http Authentication header containing your authentication token.

Using 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	Configuration Manager 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 CM)	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 Configuration Manager Cannot be modified once set

Notes:

The userName attribute also sets the user’s Federation ID (used for Single Sign-On) on create only.

Inactive users are shown as a grayed out row in Configuration Manager.

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

Configuration Manager 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 Configuration

Manager)

extension

8x8 User¹

Extension number

Present only if user is assigned an X Series license

Read-only (set from Configuration Manager)

Notes:

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.

Please 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 (VOD/VOM) 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, please 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
Users created in Configuration Manager cannot be adopted by a SCIM client. This is because a GET request will only return users who were created via SCIM in the first place
Some fields set through the SCIM API can be subsequently modified in Configuration Manager. Depending on your SCIM implementation this may lead to some inconsistency between your Identity Management System and Configuration Manager
Modification of fields other than “active” is not supported with the PATCH operation. Use PUT instead.