Admin API Guide
The Cisco Spark API includes administration APIs that allow administrators to programatically perform administration actions such as provisioning a user. By automating administration, user management and provisioning can be centralized in an existing tool, rather than using the Cisco Spark Control Hub. For example, a partner selling multiple Collaboration tools to customers can use these APIs to enable Cisco Spark provisioning through a centralized portal.
What's possible with Admin APIs?
Currently, administration is focused on User Provisioning. Using these APIs, an admin can:
- Create a user
- Update a user
- View license usage of an organization
- View available roles of an organization
- Manage Hybrid Services licenses and users
If your organization uses the Cisco Directory Connector to synchronize Cisco Spark user accounts with Active Directory accounts, then you cannot create or delete Cisco Spark users via the People API.
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, you can login here to get a development auth token with necessary scopes.
Creating an Integration that will act on behalf of an administrator can be done by including one or more of the following scopes when requesting an auth token via oAuth.
||Access to read your user's company directory|
||Access to write to your user's company directory|
||Access to write to your user's company directory|
||Access to read roles available in your user's organization|
||Access to read licenses available in your user's organizations|
||Access to read metrics in your user's organization|
||Access to read events in your user's organization. New integrations, please use spark-compliance:events_read instead|
||Access to delete messages in all rooms/spaces in your user's organization. New integrations, please use spark-compliance:messages_write instead|
||Access to read messages in all spaces in your user's organization. New integrations, please use spark-compliance:messages_read instead|
||Access to read all rooms/spaces in your user's organization. New integrations, please use spark-compliance:rooms_read instead|
||Access to read all teams in your user's organization. New integrations, please use spark-compliance:teams_read instead|
||Access to read memberships in all rooms/spaces in your user's organization. New integrations, please use spark-compliance:memberships_read instead|
||Access to delete memberships in all spaces in your user's organization. New integrations, please use spark-compliance:memberships_write instead|
||Access to read team memberships in your organization|
||Access to update team memberships in your organization|
||Access to read policies in your user's organization|
||Access to edit policies in your user's organization|
If you would like to develop against the Admin APIs but you are not an administrator of your Cisco Spark Organization, you can apply for administrator rights to our Sandbox Organization. The Admin Sandbox will allow you to use a separate Cisco Spark 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 Cisco Spark. We will create a new Cisco Spark account for this email address and assign it to the Admin Sandbox organization. This new Cisco Spark 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 Cisco Spark account or cannot have been claimed by an existing Cisco Spark 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 your home 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 Cisco Spark 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 Cisco Spark for Developers documentation as an admin, you will need to sign into the Cisco Spark 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 Cisco Spark account to firstname.lastname@example.org, requesting Admin Sandbox access, and including the email address you would like to have enabled for sandbox access.