Webex User Management API Guide

Auth method: OAuth 2.0 (Bearer token)

Setup steps

1. Register an integration at https://developer.webex.com/my-apps/new/integration.
2. Select required scopes (e.g., spark-admin:people_read, spark-admin:people_write).
3. Implement the OAuth 2.0 Authorization Code flow to obtain an access token.
4. Include the token in every request as: Authorization: Bearer .
5. Refresh tokens before expiry using the refresh_token grant; access tokens expire in 14 days by default.

Required scopes

List People

• Method: GET
• URL: https://webexapis.com/v1/people
• Watch out for: Without a filter (email, displayName, id), the endpoint returns all org users but requires spark-admin:people_read. Pagination cursor is returned in the Link response header, not the body.

Request example

GET /v1/people?email=jdoe@example.com&max=100
Authorization: Bearer <token>

Response example

{
  "items": [
    {
      "id": "Y2lzY29...",
      "emails": ["jdoe@example.com"],
      "displayName": "Jane Doe",
      "orgId": "Y2lzY29..."
    }
  ]
}

Get Person Details

• Method: GET
• URL: https://webexapis.com/v1/people/{personId}
• Watch out for: Use 'me' as personId to retrieve the authenticated user's own record.

Request example

GET /v1/people/Y2lzY29...
Authorization: Bearer <token>

Response example

{
  "id": "Y2lzY29...",
  "emails": ["jdoe@example.com"],
  "firstName": "Jane",
  "lastName": "Doe",
  "roles": [],
  "licenses": ["Y2lzY29..."]
}

Create Person

• Method: POST
• URL: https://webexapis.com/v1/people
• Watch out for: Requires spark-admin:people_write. The user receives an activation email. License IDs must be obtained from GET /licenses first.

Request example

POST /v1/people
Authorization: Bearer <token>
Content-Type: application/json
{
  "emails": ["newuser@example.com"],
  "firstName": "New",
  "lastName": "User",
  "licenses": ["Y2lzY29..."]
}

Response example

{
  "id": "Y2lzY29...",
  "emails": ["newuser@example.com"],
  "displayName": "New User",
  "created": "2024-01-15T10:00:00.000Z"
}

Update Person

• Method: PUT
• URL: https://webexapis.com/v1/people/{personId}
• Watch out for: PUT replaces the full resource; omitting optional fields may clear them. Use the full current object as a base and modify only changed fields.

Request example

PUT /v1/people/Y2lzY29...
Authorization: Bearer <token>
Content-Type: application/json
{
  "emails": ["jdoe@example.com"],
  "displayName": "Jane Doe Updated",
  "roles": ["Y2lzY29..."]
}

Response example

{
  "id": "Y2lzY29...",
  "displayName": "Jane Doe Updated",
  "lastModified": "2024-06-01T12:00:00.000Z"
}

Delete Person

• Method: DELETE
• URL: https://webexapis.com/v1/people/{personId}
• Watch out for: Deletion is permanent and immediate. Requires spark-admin:people_write. Cannot delete the last admin of an org.

Request example

DELETE /v1/people/Y2lzY29...
Authorization: Bearer <token>

Response example

HTTP 204 No Content

Get My Own Details

• Method: GET
• URL: https://webexapis.com/v1/people/me
• Watch out for: Only requires spark:people_read (non-admin scope). Returns the identity of the token owner.

Request example

GET /v1/people/me
Authorization: Bearer <token>

Response example

{
  "id": "Y2lzY29...",
  "emails": ["me@example.com"],
  "displayName": "Current User"
}

List Roles

• Method: GET
• URL: https://webexapis.com/v1/roles
• Watch out for: Role IDs are org-specific. Retrieve them before assigning roles in PUT /people/{id}.

Request example

GET /v1/roles
Authorization: Bearer <token>

Response example

{
  "items": [
    {"id": "Y2lzY29...", "name": "Full Administrator"}
  ]
}

List Licenses

• Method: GET
• URL: https://webexapis.com/v1/licenses
• Watch out for: License IDs must be passed when creating or updating users. Check consumedUnits vs totalUnits before provisioning to avoid license exhaustion errors.

Request example

GET /v1/licenses?orgId=Y2lzY29...
Authorization: Bearer <token>

Response example

{
  "items": [
    {"id": "Y2lzY29...", "name": "Webex Meetings", "totalUnits": 100, "consumedUnits": 42}
  ]
}

• Rate limits: Webex APIs enforce per-app, per-org rate limits. The People API is subject to a general API rate limit; Cisco documents a default of approximately 600 requests per minute for most admin APIs, but exact limits vary by endpoint and are enforced dynamically.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: When rate-limited, the API returns HTTP 429. The Retry-After header is included in the 429 response indicating seconds to wait. Webex documentation explicitly mentions Retry-After on 429 responses.
• Pagination method: cursor
• Default page size: 100
• Max page size: 1000
• Pagination pointer: max (page size), cursor (next-page token returned in Link header)

• Webhooks available: Yes
• Webhook notes: Webex supports webhooks via POST /webhooks. Webhooks can be registered for resource/event combinations and deliver HTTP POST payloads to a configured target URL.
• Alternative event strategy: Webex does not expose a dedicated 'people:created' or 'people:deleted' webhook event natively. Org-level user provisioning events are handled via SCIM or polling the People API.
• Webhook events: memberships:created, memberships:deleted, memberships:updated, rooms:created, rooms:updated, messages:created, meetings:started, meetings:ended

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Business or Enterprise (SSO must be configured as a prerequisite)

• Endpoint: https://webexidentity.cisco.com/scim/v2/

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (deprovision user), GET /Groups (list groups), POST /Groups (create group), PATCH /Groups/{id} (update group membership), DELETE /Groups/{id} (delete group)

Limitations:

• SSO (SAML or OIDC) must be configured before SCIM provisioning can be enabled.
• Available on Business and Enterprise plans only; not available on free or Starter plans.
• SCIM provisioning is typically configured through a supported IdP connector (Okta, Microsoft Entra ID, OneLogin) rather than direct API calls.
• The SCIM base URL is specific to Webex Identity (webexidentity.cisco.com), not the standard webexapis.com base.
• Group push via SCIM maps to Webex Teams (Spaces) membership, not org-level admin groups.

Three scenarios cover the majority of programmatic provisioning needs.

For new-hire provisioning: call GET /v1/licenses to confirm consumedUnits < totalUnits, then POST /v1/people with the target license IDs in the licenses array

the user receives an activation email immediately and there is no silent-provisioning option via REST.

For role assignment: always GET /v1/people/{personId} first to retrieve the full current object, then add the role ID from GET /v1/roles to the roles array and PUT the complete object back

omitting any existing field in a PUT will clear it, since the endpoint performs a full resource replacement.

For IdP-driven deprovisioning: route through SCIM at https://webexidentity.cisco.com/scim/v2/ rather than the REST DELETE endpoint;

the IdP sends PATCH active:false or DELETE, and Webex reclaims the license automatically.

SCIM requires SSO to be fully configured first and is restricted to Business and Enterprise plans.

Provision a new employee with a Webex Meetings license

1. GET /v1/licenses?orgId={orgId} to retrieve available license IDs and confirm consumedUnits < totalUnits for the Meetings license.
2. POST /v1/people with emails, firstName, lastName, and the Meetings license ID in the licenses array.
3. Store the returned id for future updates or deprovisioning.
4. Optionally GET /v1/people/{id} to confirm the user is active and the license is applied.

Watch out for: The new user receives an activation email immediately upon POST. If the license pool is exhausted, the API returns a 400 error; check capacity before bulk provisioning.

Assign an admin role to an existing user

1. GET /v1/roles to retrieve the role ID for 'Full Administrator' or the desired admin role.
2. GET /v1/people/{personId} to retrieve the full current user object.
3. Add the role ID to the roles array in the user object.
4. PUT /v1/people/{personId} with the full updated object including the new role.

Watch out for: PUT replaces the entire resource. Omitting existing licenses or other roles from the payload will remove them. Always base the PUT body on the current GET response.

Deprovision a departing employee via SCIM (IdP-driven)

1. Ensure SSO and SCIM provisioning are configured in the Webex Control Hub under Management > Users > User Provisioning.
2. In the IdP (e.g., Okta), unassign the user from the Webex SCIM application.
3. The IdP sends a PATCH /Users/{id} with active:false or DELETE /Users/{id} to https://webexidentity.cisco.com/scim/v2/.
4. Webex deactivates or removes the user and reclaims the license automatically.

Watch out for: SCIM deprovisioning behavior (suspend vs. delete) depends on IdP configuration. Verify the IdP's deprovisioning action setting to avoid unintended permanent deletion.

Four implementation traps account for the majority of integration bugs. First, PUT /people/{id} is a full replacement: any field absent from the request body is silently cleared, including existing license and role assignments.

Second, pagination state is returned in the HTTP Link response header as rel='next', not in the JSON body - parsers that only inspect the response body will silently drop pages. Third, the rate limit is approximately 600 requests per minute with HTTP 429 responses that include a Retry-After header;

integrations without explicit backoff logic will encounter cascading failures during bulk operations. Fourth, webhook support does not include native people:created or people:deleted events - org-level provisioning state changes must be detected by polling GET /v1/people or by relying on SCIM callbacks, not webhooks.