8x8 User Management API Guide

Auth method: Bearer Token (static API token generated from 8x8 Admin Console; not OAuth 2.0)

Setup steps

1. Log in to 8x8 Admin Console.
2. From Home, navigate to Identity and Security.
3. In the User Provisioning Integration (SCIM) section, enable the SCIM toggle.
4. Select 'Other SCIM Provider' (or Azure AD / Okta for pre-built integrations).
5. Copy the 8x8 URL (SCIM base URL including your CUSTOMER_ID) and the 8x8 API Token.
6. Pass the API Token as a Bearer token in the HTTP Authorization header on all SCIM requests.
7. Note: If an external IdP (Azure AD or Okta) is already configured, the same token can be reused for GET-only operations by a secondary client.

List Users

• Method: GET
• URL: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2/Users
• Watch out for: Use startIndex (1-based) and count for pagination. If an external IdP is active, a secondary SCIM client may only perform GET operations.

Request example

GET /scim/v2/Users?startIndex=1&count=50
Authorization: Bearer {API_TOKEN}

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 120,
  "startIndex": 1,
  "itemsPerPage": 50,
  "Resources": [{...}]
}

Get User

• Method: GET
• URL: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2/Users/{userId}
• Watch out for: The userId in the path is the 8x8-internal id, not the userName or externalId.

Request example

GET /scim/v2/Users/abc123
Authorization: Bearer {API_TOKEN}

Response example

{
  "id": "abc123",
  "userName": "jdoe",
  "name": {"givenName": "John", "familyName": "Doe"},
  "active": true,
  "emails": [{"value": "john@abc.com", "type": "work", "primary": true}]
}

Create User

• Method: POST
• URL: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2/Users
• Watch out for: userName, givenName, familyName, and exactly one work email are required. License must be manually assigned in Admin Console after provisioning. New users do not appear in Company Directory automatically.

Request example

POST /scim/v2/Users
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
  "userName": "jdoe",
  "name": {"givenName": "John", "familyName": "Doe"},
  "active": true,
  "emails": [{"value": "john@abc.com", "type": "work", "primary": true}]
}

Response example

HTTP 201 Created
{
  "id": "abc123",
  "userName": "jdoe",
  "active": true
}

Replace User (full update)

• Method: PUT
• URL: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2/Users/{userId}
• Watch out for: PUT must include ALL attributes regardless of what is being changed. Omitting an attribute is treated as clearing it to null/empty.

Request example

PUT /scim/v2/Users/abc123
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
  "userName": "jdoe",
  "name": {"givenName": "John", "familyName": "Doe"},
  "active": true,
  "emails": [{"value": "john@abc.com", "type": "work", "primary": true}],
  "title": "Senior Manager"
}

Response example

HTTP 200 OK
{"id": "abc123", "userName": "jdoe", "title": "Senior Manager", "active": true}

Partial Update User (deactivate/activate)

• Method: PATCH
• URL: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2/Users/{userId}
• Watch out for: PATCH only supports modifying the 'active' field. Modification of any other field via PATCH is not supported; use PUT instead.

Request example

PATCH /scim/v2/Users/abc123
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{"op": "replace", "value": {"active": false}}]
}

Response example

HTTP 200 OK
{"id": "abc123", "userName": "jdoe", "active": false}

Deactivate User (DELETE)

• Method: DELETE
• URL: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2/Users/{userId}
• Watch out for: DELETE does NOT delete the user. It deactivates the user (sets active=false). Hard deletion is not supported via SCIM.

Request example

DELETE /scim/v2/Users/abc123
Authorization: Bearer {API_TOKEN}

Response example

HTTP 204 No Content

• Rate limits: No publicly documented rate limits specific to the SCIM user-management API. The 8x8 Analytics End-to-End Journey API documents 10 requests per 60-second sliding window as a reference for developer APIs generally. SCIM-specific limits are not published.
• Rate-limit headers: No
• Retry-After header: Yes
• Rate-limit notes: When rate limits are exceeded on 8x8 APIs, a 429 status code is returned with a Retry-After header. SCIM-specific rate limit headers are not documented in official sources.
• Pagination method: offset
• Default page size: 0
• Max page size: 0
• Pagination pointer: startIndex and count (SCIM 2.0 standard parameters)

• Webhooks available: No
• Webhook notes: No webhooks are documented for the 8x8 SCIM user-management API. The 8x8 developer portal references a webhooks management API in the context of CPaaS/Connect (messaging), not for user provisioning or Admin Console events.
• Alternative event strategy: Use polling via GET /Users to detect changes, or rely on IdP-driven sync cycles (Azure AD syncs approximately every 40 minutes; Okta has its own cycle).

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Any 8x8 X Series subscription (quote-based). SSO must be configured as a prerequisite.

• Endpoint: https://platform-cloud.8x8.com/udi/customers/{CUSTOMER_ID}/scim/v2

• Supported operations: GET /Users (list all users, paginated), GET /Users/{id} (get single user), POST /Users (create user), PUT /Users/{id} (full replace/update), PATCH /Users/{id} (partial update; active field only), DELETE /Users/{id} (deactivates user, does not delete)

Limitations:

• DELETE results in deactivation only; hard deletion is not supported.
• PATCH only supports modifying the 'active' field; all other field updates require PUT.
• PUT must include all attributes; omitted fields are cleared to null.
• License (X Series) assignment must be done manually in Admin Console after provisioning.
• Cannot set cost center, user profile, or work phone number via SCIM.
• Cannot update the 'site' field once it has been set via SCIM.
• Users provisioned via SCIM do not automatically appear in the Company Directory; must be manually enabled in Admin Console.
• Only one active SCIM write client is supported; if an external IdP (Azure/Okta) is configured, a secondary client is limited to GET operations only.
• 8x8 custom schema URN is urn:ietf:params:scim:schemas:extension:8x8:1.1:User.
• SSO (SAML) must be configured before enabling SCIM provisioning.
• On-premise Active Directory is not directly supported; requires Azure AD Connect hybrid setup.

Three workflows cover the practical API surface. Onboarding: POST to /Users with userName, name.

givenName, name. familyName, and one work email; receive a 201 with the 8x8-internal id; then manually assign a license and enable directory visibility in Admin Console - SCIM cannot do either.

Profile updates (department, title, locale): retrieve the full user object via GET /Users/{id}, modify the target fields, and PUT the complete object back - omitting any attribute clears it to null, so partial PUTs will silently corrupt data.

Deactivation: PATCH /Users/{id} with op:replace on active:false, or send DELETE /Users/{id} - both result in deactivation only; hard deletion is not available via API. Confirm state with a follow-up GET.

Onboard a new employee via SCIM

1. Ensure SSO is configured and SCIM is enabled in Admin Console (Identity and Security > User Provisioning Integration).
2. POST to /scim/v2/Users with required fields: userName, name.givenName, name.familyName, and one work email. Include optional fields: locale, timezone, title, department, and urn:ietf:params:scim:schemas:extension:8x8:1.1:User.site.
3. Receive HTTP 201 with the 8x8-assigned user id.
4. Manually assign an X Series license to the new user in Admin Console (SCIM cannot do this).
5. Manually enable the user in the Company Directory in Admin Console if directory visibility is required.

Watch out for: Omitting the site field on create is fine, but once set it cannot be changed via SCIM. License assignment and directory visibility are always manual steps.

Deactivate a departing employee

1. Identify the user's 8x8 internal id via GET /scim/v2/Users?filter=userName eq "jdoe" or list all users.
2. Send PATCH /scim/v2/Users/{id} with Operations: [{op: replace, value: {active: false}}], or send DELETE /scim/v2/Users/{id}.
3. Confirm the user's active status is false via GET /scim/v2/Users/{id}.
4. The user will immediately lose access to 8x8 Work for Desktop and Mobile.

Watch out for: DELETE does not remove the user record; it only deactivates. If using an IdP like Azure AD or Okta, disabling the user in the IdP triggers deactivation automatically on the next sync cycle (~40 min).

Update user profile attributes (e.g., department, title)

1. Retrieve the full current user object via GET /scim/v2/Users/{id}.
2. Modify the desired fields in the retrieved object (e.g., update title and department).
3. Send a PUT /scim/v2/Users/{id} with the complete modified user object including ALL attributes.
4. Confirm changes via GET /scim/v2/Users/{id}.

Watch out for: Do not use PATCH for attribute changes other than 'active' - it is not supported. Always use PUT and always include the full user object to avoid accidentally clearing fields.

The PATCH limitation is the most operationally dangerous constraint: only the active field is supported via PATCH, and this is not enforced with a clear error in all cases - developers expecting standard SCIM PATCH behavior will silently fail to update attributes.

PUT-as-full-replace compounds this: any attribute omitted from the body is treated as a clear, meaning a naive update that fetches and re-PUTs a partial object can wipe existing data.

The site field (8x8 custom extension urn:ietf:params:scim:schemas:extension:8x8:1.1:User.site) is immutable once set via SCIM - there is no API path to correct it; it requires direct Admin Console intervention. License assignment, cost center, work phone number, and profile picture are entirely outside SCIM scope.

Rate limits for the SCIM endpoint are not publicly documented; the only published reference is 10 requests per 60-second window from the Analytics API, which should not be assumed to apply here. Plan for 429 responses with Retry-After headers and implement backoff accordingly.