User Provisioning with 8x8 SCIM API
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:
- Using a pre-built integration with either Microsoft Azure AD or Okta. For more information on setting up these integrations see:
- 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:
- Log in to Admin Console.
- From Home, click on Identity and Security.
- 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.
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:
|
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
|
|
|
Notes:
|
Get All Users
Gets a list of all users in the company. For pagination,
specify numbers for startIndex and count.
Operation: GET
URL:
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:
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:
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:
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:
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:
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.
Related Articles
Azure (Entra) AD: 8x8 Single Sign-On (SSO) and User Provisioning (SCIM) Configuration
Objective Configure Microsoft Azure (Entra) SAML 2.0 SSO for Admin Console. Instructions and information covered in this article include: Configuring your Azure AD service and 8x8 Admin Console for Microsoft user SSO login to your 8x8 applications ...User Provisioning Attribute Mappings for Microsoft Azure (Entra) AD
Overview User provisioning attribute mappings for both default and advanced sets. Applies To 8x8 Admin Console Microsoft Azure (Entra) Active Directory (Azure AD) Single Sign-On (SSO) Default Attribute Mappings This table shows the default set of ...Gong.io Integration Guide for 8x8 Services
Objective Integrate Gong.io with 8x8 X Series accounts, allowing Gong.io to access customer call recordings and user data on the 8x8 platform. This process must be performed by each customer wishing to implement this integration. IMPORTANT: The 8x8 ...Viewing and Creating X Series User Roles
Objective View and create user roles in Admin Console using role-based access control (RBAC). Applies To Admin Console Role-Based Access Control Procedure Only users with the Company Admin role and IT Admin Role can view and create user roles. ...Nomadic 911 Confirm Provisioning and User Enablement
Objective This brief article will show you how to identify when your 8x8 service has been provisioned in 8x8 Admin Console for Nomadic 911 service, and when your users are specifically enabled for the service. Applies To 8x8 Nomadic 911 Service 8x8 ...