Admin API guide
Manage Webex users, licenses, and hybrid services programmatically with the Webex Admin APIs.
anchorWhat's possible with Admin APIs
anchorThe 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:
- Create a user
- Update a user
- View license usage of an organization
- View available roles of an organization
- Manage Hybrid Services licenses and users
- View information about Hybrid Clusters or Hybrid Connectors
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
anchorFull 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
anchorUse 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:
spark-admin:devices_readspark-admin:devices_writespark-admin:licenses_readspark-admin:organizations_readspark-admin:people_readspark-admin:people_writespark-admin:places_readspark-admin:places_writespark-admin:resource_group_memberships_readspark-admin:resource_group_memberships_writespark-admin:resource_groups_readspark-admin:roles_readspark-admin:workspaces_readspark-admin:broadworks_enterprises_readspark-admin:hybrid_clusters_readspark-admin:hybrid_connectors_readspark-admin:broadworks_subscribers_readspark-admin:broadworks_subscribers_writespark-admin:locations_writespark-admin:locations_readspark-admin:broadworks_enterprises_writeanchorReports API
anchorThe 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. Each user is limited to 50 reports. If a user tries to create more than 50 reports, an error will be returned by the API. See below for errors you may encounter from the API.
Using the Reports API
First, list the available report templates. These templates are available for you to use when creating a 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
idreturned. This is the report's ID. You will need this later to download it.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.
When the report is ready, use the download link in the response to download 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 Code | ErrorCode | Description |
|---|---|---|
| 400 | 1000 | Reach the limit for creating reports |
| 400 | 1001 | Report Template ID not found |
| 400 | 1002 | Over the maximum date selection allow |
| 400 | 1003 | No access to sites that you do not belong to |
| 400 | 1004 | SiteUrl cannot be empty for site level template |
| 400 | 1008 | reportId does not exist |
| 400 | 1009 | [field required for validation, for example: templateId, siteList, etc ] can not be empty! |
| 400 | 1016 | Either none or both of from and to query parameter must be present in request |
| 401 | 1010 | Authorization token not provided |
| 401 | 1011 | Authorization token wrong or expired |
| 401 | 1012 | Feature toggle not enabled |
| 401 | 1014 | The user does not have allowed role |
| 401 | 1018 | CI Access Token or scope of the token is not valid! |
| 403 | 1005 | Not allow to generate ui report by api |
| 403 | 1006 | Not allow to delete others report |
| 429 | 1007 | Number of downloads for this report has reached the limit within 24 hrs |
anchorDeveloper Sandbox
anchorIf you would like to develop against the Admin APIs but you are not an administrator of your Webex Organization, you can request a Developer Sandbox. A Developer Sandbox provides you with a Webex administrator account for a "dummy" organization you can use to develop and test bots, integrations, and embedded apps outside of your primary organization.
For more information and to request a Developer Sandbox organization see the Developer Sandbox Guide.