openapi: 3.0.0
info:
title: Webex Admin Address Book SCIM 2 Users API
version: 1.0.0
description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: SCIM 2 Users
paths:
/identity/scim/{orgId}/v2/Users:
post:
responses:
'201':
description: Created
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserResponse'
example:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:User
- urn:scim:schemas:extension:cisco:webexidentity:2.0:User
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
id: 3426a8e3-d414-4bf0-a493-4f6787632a13
userName: user1@example.com
active: true
roles:
- value: id_full_admin
type: cirole
display: Full administrator
name:
familyName: Joestar
givenName: Jonathan
middleName: Jane
honorificPrefix: Mr.
honorificSuffix: III
displayName: Mr. Jonathan Jane Joestar, III
nickName: JoJo
emails:
- value: user1@example.home.com
type: home
display: home email description
- value: user1@example.com
type: work
primary: true
userType: user
profileUrl: https://jojowiki.com/Jonathan_Joestar
title: Sales manager
preferredLanguage: en_US
locale: en_US
externalId: externalIdValue
timezone: America/Los_Angeles
phoneNumbers:
- value: 400 123 1234
type: work
primary: true
display: work phone number
photos:
- value: https://photos.example.com/profilephoto/72930000000Ccne/F
type: photo
primary: true
display: photo description
addresses:
- type: work
streetAddress: 100 Universal City Plaza
locality: Hollywood
region: CA
postalCode: '91608'
country: US
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
employeeNumber: 518-8888-888
costCenter: costCenter 123
organization: Cisco webexidentity
division: division 456
department: department 789
manager:
value: b5717a4a-0169-43b2-ac3c-db20ba4e72cd
displayName: Identity Administrator
example: https://integration.webexapis.com/identity/scim/0ae87ade-8c8a-4952-af08-318798958d0c/v2/Users/b5717a4a-0169-43b2-ac3c-db20ba4e72cd
urn:scim:schemas:extension:cisco:webexidentity:2.0:User:
accountStatus:
- active
sipAddresses:
- value: sipAddress value1
type: enterprise
primary: true
display: sipAddress1 description
managedOrgs:
- orgId: 75fe2995-24f5-4831-8d2c-1c2f8255912e
role: id_full_admin
managedGroups:
- orgId: 75fe2995-24f5-4831-8d2c-1c2f8255912e
groupId: d178e396-aa06-42cd-ab98-5124eb3b1926
role: id_full_admin
externalAttribute1:
- source: Source.1_7ddf1f2c-2985-4c37-a450-d58bbc201750
value: externalAttribute1_value
externalAttribute2:
- source: Source.2_7ddf1f2c-2985-4c37-a450-d58bbc201750
value: externalAttribute2_value
extensionAttribute1:
- extensionAttribute1_Item1
- extensionAttribute1_Item2
extensionAttribute2:
- extensionAttribute2_Item1
- extensionAttribute2_Item2
- extensionAttribute2_Item3
meta:
organizationId: 0ae87ade-8c8a-4952-af08-318798958d0c
meta:
resourceType: User
location: http://integration.webexapis.com/identity/scim/0ae87ade-8c8a-4952-af08-318798958d0c/v2/Users/3426a8e3-d414-4bf0-a493-4f6787632a13
version: W/"76678575420"
created: '2023-01-11T17:38:31.605Z'
lastModified: '2023-01-11T17:38:31.605Z'
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Create a user
operationId: Create a user
description: "The SCIM 2 /Users API provides a programmatic way to manage users in Webex Identity using The Internet Engineering Task Force standard SCIM 2.0 standard as specified by [RFC 7643 SCIM 2.0 Core Schema ](https://datatracker.ietf.org/doc/html/rfc7643) and [RFC 7644 SCIM 2.0 Core Protocol](https://datatracker.ietf.org/doc/html/rfc7644). The WebEx SCIM 2.0 APIs allow clients supporting the SCIM 2.0 standard to manage users, and groups within Webex. Webex supports the following SCIM 2.0 Schemas:\n\n• urn:ietf:params:scim:schemas:core:2.0:User\n\n• urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\n\n• urn:scim:schemas:extension:cisco:webexidentity:2.0:User\n\n<br/>\n\n**Authorization**\n\nOAuth token rendered by Identity Broker.\n\n<br/>\n\nOne of the following OAuth scopes is required:\n\n- `identity:people_rw`\n\n<br/>\n\nThe following administrators can use this API:\n\n- `id_full_admin`\n\n- `id_user_admin`\n\n<br/>\n\n**Usage**:\n\n1. Input JSON must contain schema: \"urn:ietf:params:scim:schemas:core:2.0:User\".\n\n2. Support 3 schemas :\n - \"urn:ietf:params:scim:schemas:core:2.0:User\"\n - \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\"\n - \"urn:scim:schemas:extension:cisco:webexidentity:2.0:User\"\n\n3. Unrecognized schemas (ID/section) are ignored.\n\n4. Read-only attributes provided as input values are ignored.\n\n The following roles cannot be assigned to a user:\n\n1. Location Admin\n\n2. Webex Site Admin"
tags:
- SCIM 2 Users
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for user's organization.
required: true
example: 0ae87ade-8c8a-4952-af08-318798958d0c
schema:
type: string
requestBody:
content:
application/json:
example:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:User
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
- urn:scim:schemas:extension:cisco:webexidentity:2.0:User
userName: user1@example.com
userType: user
title: Sales manager
active: true
preferredLanguage: en_US
locale: en_US
timezone: America/Los_Angeles
profileUrl: https://jojowiki.com/Jonathan_Joestar
externalId: externalIdValue
displayName: Mr. Jonathan Jane Joestar, III
nickName: JoJo
name:
givenName: Sarah
familyName: Henderson
middleName: Jane
honorificPrefix: Mr.
honorificSuffix: III
roles:
- value: id_full_admin
type: cirole
display: Full administrator
phoneNumbers:
- value: 400 123 1234
type: work
display: work phone number
primary: true
photos:
- value: https://photos.example.com/profilephoto/72930000000Ccne/F
type: photo
display: photo description
primary: true
addresses:
- type: work
streetAddress: 100 Universal City Plaza
locality: Hollywood
region: CA
postalCode: '91608'
country: US
emails:
- value: user1@example.home.com
type: home
display: home email description
primary: false
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
costCenter: costCenter 123
organization: Cisco webexidentity
division: division 456
department: department 789
employeeNumber: 518-8888-888
manager:
value: b5717a4a-0169-43b2-ac3c-db20ba4e72cd
urn:scim:schemas:extension:cisco:webexidentity:2.0:User:
accountStatus: active
sipAddresses:
- value: sipAddress value1
type: enterprise
display: sipAddress1 description
primary: true
managedOrgs:
- orgId: 75fe2995-24f5-4831-8d2c-1c2f8255912e
role: id_full_admin
managedGroups:
- orgId: 0ae87ade-8c8a-4952-af08-318798958d0c
groupId: 3936af3e-15ff-43d1-9ef5-66c569ef34f5
role: location_admin
extensionAttribute*: []
externalAttribute*:
- source: Source.1_7ddf1f2c-2985-4c37-a450-d58bbc201750
value: externalAttribute1_value
schema:
$ref: '#/components/schemas/PostUser'
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SearchUserResponse'
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Search users
operationId: Search users
description: '<br/>
**Authorization**
OAuth token rendered by Identity Broker.
<br/>
One of the following OAuth scopes is required:
- `identity:people_rw`
- `identity:people_read`
<br/>
The following administrators can use this API:
- `id_full_admin`
- `id_user_admin`
- `id_readonly_admin`
- `id_device_admin`
<br/>'
tags:
- SCIM 2 Users
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for user's organization.
required: true
example: 0ae87ade-8c8a-4952-af08-318798958d0c
schema:
type: string
- name: filter
in: query
description: 'The URL encoded filter. If the value is empty, the API will return all users under the organization.
The examples below show some search filters:
- `userName` eq "user1@example.com"
- `userName` sw "user1@example"
- `userName` ew "example"
- `phoneNumbers` [ type eq "mobile" and value eq "14170120"]
- `urn:scim:schemas:extension:cisco:webexidentity:2.0:User:meta.organizationId` eq "0ae87ade-8c8a-4952-af08-318798958d0c"
- For more filter patterns, please check [filtering](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2).
| **Attributes** | **Operators** |
|-----|-----|
| **SCIM Core** | ---- |
| `id` | eq |
| `userName` | eq sw ew |
| `name.familyName` | eq sw ew |
| `name.givenName` | eq sw |
| `name.middleName` | eq sw |
| `name.formatted` | eq sw |
| `displayName` | eq sw ew |
| `nickName` | eq sw ew |
| `emails.display` | eq sw ew |
| `emails.value` | eq sw ew |
| `phoneNumbers.value` | eq sw ew |
| `phoneNumbers.display` | eq sw ew |
| **Enterprise Extensions** | ---- |
| `employeeNumber` | eq sw ew |
| `costCenter` | eq sw ew |
| `organization` | eq sw ew |
| `division` | eq sw ew |
| `department` | eq sw ew |
| `manager.value` | eq |
| `manager.displayName` | eq sw ew |'
example: userName%20Eq%20%22user1%40example.com%22%20or%20userName%20Eq%20%22user2%40example.com%22
schema:
type: string
- name: attributes
in: query
description: A multi-valued list of string names for resource attributes to return in the response, like 'userName,department,emails'. It supports the SCIM id 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User,userName'. The default is empty, all attributes will be returned
example: urn:ietf:params:scim:schemas:core:2.0:User
schema:
type: string
- name: excludedAttributes
in: query
description: A multi-valued list of strings names for resource attributes to be removed from the default set of attributes to return. The default is empty, all attributes will be returned
example: nickName,userType
schema:
type: string
- name: sortBy
in: query
description: A string for the attribute whose value can be used to order the returned responses. Now we only allow `userName`, `id`, `meta.lastModified` to sort.
example: userName
schema:
type: string
- name: sortOrder
in: query
description: A string for the order in which the 'sortBy' parameter is applied. Allowed values are 'ascending' and 'descending'.
example: ascending
schema:
type: string
- name: startIndex
in: query
description: An integer for the 1-based index of the first query result. The default is 1.
example: '1'
schema:
type: string
- name: count
in: query
description: An integer for the maximum number of query results per page. The default is 100.
example: '10'
schema:
type: string
- name: returnGroups
in: query
description: Define whether the group information needs to be returned. The default is false.
example: 'false'
schema:
type: string
- name: includeGroupDetails
in: query
description: Define whether the group information with details needs to be returned. The default is false.
example: 'false'
schema:
type: string
- name: groupUsageTypes
in: query
description: Returns groups with details of the specified group type.
example: '``'
schema:
type: string
/identity/scim/{orgId}/v2/Users/{userId}:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserResponse'
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Get a user
operationId: Get a user
description: '<br/>
**Authorization**
OAuth token rendered by Identity Broker.
<br/>
One of the following OAuth scopes is required:
- `identity:people_rw`
- `identity:people_read`
<br/>
The following administrators can use this API:
- `id_full_admin`
- `id_user_admin`
- `id_readonly_admin`
- `id_device_admin`
<br/>'
tags:
- SCIM 2 Users
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for user's organization.
required: true
example: 0ae87ade-8c8a-4952-af08-318798958d0c
schema:
type: string
- name: userId
in: path
description: Webex Identity assigned user identifier.
required: true
example: 3426a8e3-d414-4bf0-a493-4f6787632a13
schema:
type: string
put:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserResponse'
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Update a user with PUT
operationId: Update a user with PUT
description: "<br/>\n\n**Authorization**\n\nOAuth token rendered by Identity Broker.\n\n<br/>\n\nOne of the following OAuth scopes is required:\n\n- `identity:people_rw`\n\n<br/>\n\nThe following administrators can use this API:\n\n- `id_full_admin`\n\n- `id_user_admin`\n\n<br/>\n\n**Usage**:\n\n1. Input JSON must contain schema: \"urn:ietf:params:scim:schemas:core:2.0:User\".\n\n2. Support 3 schemas :\n - \"urn:ietf:params:scim:schemas:core:2.0:User\"\n - \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\"\n - \"urn:scim:schemas:extension:cisco:webexidentity:2.0:User\"\n\n3. Unrecognized schemas (ID/section) are ignored.\n\n4. Read-only attributes provided as input values are ignored.\n\n5. User `id` will not be changed.\n\n6. `meta`.`created` will not be changed.\n\n7. The PUT API replaces the contents of the user's data with the data in the request body. All attributes specified in the request body will replace all existing attributes for the `userId` specified in the URL. Should you wish to replace or change some attributes as opposed to all attributes please refer to the SCIM PATCH operation https://developer.webex.com/docs/api/v1/scim2-user/update-a-user-with-patch."
tags:
- SCIM 2 Users
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for user's organization.
required: true
example: 0ae87ade-8c8a-4952-af08-318798958d0c
schema:
type: string
- name: userId
in: path
description: Webex Identity assigned user identifier.
required: true
example: 3426a8e3-d414-4bf0-a493-4f6787632a13
schema:
type: string
requestBody:
content:
application/json:
example:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:User
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
- urn:scim:schemas:extension:cisco:webexidentity:2.0:User
userName: user1Changed@example.com
userType: user
title: Sales manager
active: true
preferredLanguage: en_US
locale: en_US
timezone: America/Los_Angeles
profileUrl: https://jojowiki.com/Jonathan_Joestar
externalId: externalIdNewValue
displayName: Mr. Jonathan Jane Joestar, III
nickName: JoJo
roles:
- value: id_full_admin
type: cirole
display: Full administrator
phoneNumbers:
- value: 400 123 1234
type: work
display: work phone number
primary: true
photos:
- value: https://photos.example.com/profilephoto/72930000000Ccne/F
type: photo
display: photo description
primary: true
addresses:
- type: work
streetAddress: 100 Universal City Plaza
locality: Hollywood
region: CA
postalCode: '91608'
country: US
emails:
- value: user1@example.home.com
type: home
display: home email description
primary: false
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
costCenter: costCenter 123
organization: Cisco webexidentity
division: division 456
department: department 789
employeeNumber: 518-8888-888
manager:
value: b5717a4a-0169-43b2-ac3c-db20ba4e72cd
urn:scim:schemas:extension:cisco:webexidentity:2.0:User:
accountStatus: active
sipAddresses:
- value: sipAddress value1
type: enterprise
display: sipAddress1 description
primary: true
managedOrgs:
- orgId: 75fe2995-24f5-4831-8d2c-1c2f8255912e
role: id_full_admin
managedGroups:
- orgId: 0ae87ade-8c8a-4952-af08-318798958d0c
groupId: 3936af3e-15ff-43d1-9ef5-66c569ef34f5
role: location_admin
extensionAttribute*: []
externalAttribute*:
- source: Source.1_7ddf1f2c-2985-4c37-a450-d58bbc201750
value: externalAttribute1_value
schema:
$ref: '#/components/schemas/PutUser'
patch:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserResponse'
example:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:User
- urn:scim:schemas:extension:cisco:webexidentity:2.0:User
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
id: 3426a8e3-d414-4bf0-a493-4f6787632a13
userName: user1Changed@example.com
active: true
roles:
- value: id_full_admin
type: cirole
display: Full administrator
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-scim-2-users-api-openapi.yml