Admin API

Manage Webex users, licenses, and hybrid services programmatically with the Webex Admin APIs.

anchorWhat's possible with Admin APIs
anchor

The Webex APIs include several APIs that allow administrators to programmatically perform administrative actions such as provisioning a user or assigning a license to a user. By automating administration, user management and provisioning can be performed from an existing tool, rather than using the Webex Control Hub.

Using these APIs, an admin can, for example:

If your organization uses the Cisco Directory Connector to synchronize Webex user accounts with Active Directory accounts, then you cannot create or delete Webex users via the People API.

anchorAdmin Audit Events
anchor

Full administrators for an organization can use the Admin Audit Events API to retrieve information about significant actions taken by administrators in Webex Control Hub. See this article for detailed information about the types of events you can retrieve.

Administrators with accounts created before 2019 who have never logged into Webex Control Hub will need to log into Webex Control Hub at least once to enable access to the Admin Audit Events API.

anchorAuthentication
anchor

Use of these APIs requires you to be an administrator of an organization. If you are not an administrator of an organization, but wish to develop against these APIs, see below for instructions on how to get administrator access to an Administration Sandbox organization.

If you are an administrator, log into this site to get a development auth token with the necessary scopes.

To create an Integration that will act on behalf of an administrator, include one or more of the following scopes when requesting an auth token via OAuth:

Scope
Usage
spark-admin:broadworks_enterprises_write
Change BroadWorks Enterprise configuration, provisioned as part of Webex for BroadWorks Solution.
spark-admin:devices_read
See details for any device in your organization
spark-admin:devices_write
Create, update and delete devices and device configurations in your organization
spark-admin:licenses_read
Access to read licenses available in your user's organizations
spark-admin:organizations_read
Access to read your user's organizations
spark-admin:people_read
Access to read your user's company directory
spark-admin:people_write
Access to write to your user's company directory
spark-admin:places_read
See details for any places and place service in your organization
spark-admin:places_write
Create, update and delete any place and place service in your organization
spark-admin:resource_group_memberships_read
Access to read your organization's resource group memberships
spark-admin:resource_group_memberships_write
Access to update your organization's resource group memberships
spark-admin:resource_groups_read
Access to read your organization's resource groups
spark-admin:roles_read
Access to read roles available in your user's organization
spark-admin:broadworks_enterprises_read
Read or List BroadWorks Enterprise, provisioned as part of Webex for BroadWorks Solution.
spark-admin:hybrid_clusters_read
Access to read hybrid clusters for your organization
spark-admin:hybrid_connectors_read
Access to read hybrid connectors for your organization
spark-admin:broadworks_subscribers_read
Read or List BroadWorks Subscribers, provisioned as part of Webex for BroadWorks Solution.
spark-admin:broadworks_subscribers_write
Provision, Update or Remove a BroadWorks Subscriber as part of Webex for BroadWorks Solution.
anchorReports API
anchor

The Webex Reports API is available for Organizations with Pro Pack for Cisco Webex Control Hub. The analytics:read_all scope is required to work with reports.

Reports are only visible to the user who created the report. Organizations are limited to 50 reports. If you try to create a report when an organization already has 50 reports, an error will be returned by the API. See below for errors you may encounter from the API.

Using the Reports API

  1. List Report Templates

    First, list the available report templates. These templates are available for you to use when creating a report.

  2. Create the Report

    Determine which template you want to use to create the report. Specify the date range for the report when creating it.

    After creating the report, make note of the id returned. This is the report's ID. You will need this later to download it.

  3. Check the Report's Status

    While the report is generated, you can check on the status of the report by retrieving the report with the ID you noted in the previous step.

  4. Download the Report

    When the report is ready, use the download link in the response to download the report.

  5. Delete the Report

    Organizations may keep up to 50 reports at any time. After you've created and downloaded your report, delete it to make room for the next report.

Reports API Errors

If you encounter an error when creating a report, the response will include an ErrorCode. See below for more information about the error.

HTTP CodeErrorCodeDescription
4001000Reach the limit for creating reports
4001001Report Template ID not found
4001002Over the maximum date selection allow
4001003No access to sites that you do not belong to
4001004SiteUrl cannot be empty for site level template
4001008reportId does not exist
4001009[field required for validation, for example: templateId, siteList, etc ] can not be empty!
4001016Either none or both of from and to query parameter must be present in request
4011010Authorization token not provided
4011011Authorization token wrong or expired
4011012Feature toggle not enabled
4011014The user does not have allowed role
4011018CI Access Token or scope of the token is not valid!
4031005Not allow to generate ui report by api
4031006Not allow to delete others report
4291007Number of downloads for this report has reached the limit within 24 hrs
anchorAdministration Sandbox
anchor

If you would like to develop against the Admin APIs but you are not an administrator of your Webex Organization, you can apply for administrator rights to our Sandbox Organization. The Admin Sandbox will allow you to use a separate Webex account that is an administrator in a dummy organization for purposes of testing and developing your code.

Use of the Admin Sandbox requires that you understand and agree to the following:

  • You will need a separate email address from the one you currently use for Webex. We will create a new Webex account for this email address and assign it to the Admin Sandbox organization. This new Webex account will be an administrator of the Admin Sandbox Organization.
  • The email address you use for the Sandbox account cannot have been previously used for a Webex account and cannot be associated with a domain that has been claimed by an existing Webex organization. This means an alias for your work email address will probably not work, as your company has likely claimed your entire email domain for their Organization. Using a personal email address or a web email service is recommended.
  • You will be an admin in the Sandbox Organization, along with every other developer who has been granted access to the Sandbox organization. This means you will have the ability to remove other users, claim domains, and other functions a Webex organization admin has the ability to do. Play nice. Kicking other users, altering data, and generally monkeying about in the admin console won't be tolerated and we'll permanently ban you from the Sandbox if you're being malicious.
  • To use the Admin APIs or the interactive Webex for Developers documentation as an admin, you will need to sign into the Webex for Developers web site with the new administrator account using your alternate email address. You'll need to generate authentication tokens as this administrator account, rather than from your normal account. Your normal account will not have any access to the administrative APIs or the Admin Sandbox.
  • When your account is created for the Admin Sandbox, you will receive an email inviting you to administer the organization. You will need to follow the instructions in that email to complete your activation.

To request access to the administrator sandbox, send an email from the email address used on your existing Webex account to devsupport@webex.com, requesting Admin Sandbox access, and including the email address you would like to have enabled for sandbox access.