Skip to main content
User Provisioning with 8x8 SCIM API
8x8 Support

User Provisioning with 8x8 SCIM API

 

Objective

The objective of this document is to 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

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 a number of ways depending on your circumstances:

  1. Azure AD: If you are using Single Sign-On integration with Microsoft Azure Active Directory (but not user provisioning integration) then you can obtain an authentication token from Admin Console.
  2. Okta: If you are using Single Sign-On integration with Okta, then you can obtain an authentication token from Admin Console but will need to contact 8x8 Support to allow non-SCIM users to be retrieved via the SCIM API.
  3. Other or Google SSO: If you are using Single Sign-On integration with any other identity provider (either via the “Other SAML SSO provider” or “Google” options) then you will need to contact 8x8 support to provide the API URL and authentication token.

Note: If you are already using SCIM 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.

Obtaining an 8x8 API token for Azure AD

You can generate an API token for Azure AD without contacting 8x8 Support.

Currently it's required that you permanently enable and configure Azure AD in 8x8 Admin Console Identity Management to generate and maintain that API token. Doing this will not conflict with use of the API.

See the section Configure an authentication token in 8x8 Admin Console for instructions on how to accomplish this.

Obtaining an 8x8 API token for Okta

You can generate a 8x8 API token for Okta using the same method as described above for Azure AD, but you must contact 8x8 Support to allow non-SCIM users to be retrieved via the SCIM API.

To accomplish this:

  1. Navigate to the Procedure > Integration Prerequisites section of the following article:
  2. Configure and save your 8x8 Admin Console Identity Management settings for Okta SSO. This is required to preserve the API token.
  3. Finally if needed, open a new 8x8 Support case and request for allowing non-SCIM Okta users to be retrieved via the SCIM API.

Obtaining an 8x8 API token for other identity providers

A new 8x8 Support case must be opened to request an 8x8 API URL and authentication token for identity providers other than Azure AD and Okta.

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

8x8 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 8x8 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 8x8 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 8x8 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

8x8 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 8x8 Admin Console)

extension 8x8 User¹ Extension number

Present only if user is assigned an X Series license


Read-only (set from 8x8 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.

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 (Work for Desktop/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, 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 8x8 Admin Console 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 8x8 Admin Console.  Depending on your SCIM implementation this may lead to some inconsistency between your Identity Management System and 8x8 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.
  • Was this article helpful?