Integrations & Authorization

Add features from third-party services to Webex Teams or perform actions on behalf of another user with Integrations.

anchorWhat are Integrations?
anchor

Integrations are how you request permission to invoke Webex Teams APIs on behalf of another user. To do this in a secure way Webex Teams supports the OAuth 2 standard which allows 3rd party integrations to get a temporary access token for authenticating API calls instead of asking users for their password.

If you're sure that your integrations require authenticating on behalf of another Webex Teams user, read on, we'll get you there in a few easy steps:

  1. Register your integration with Webex Teams
  2. Request permission using an OAuth Grant Flow
  3. Exchange the resulting Authorization Code for an Access Token
  4. Use the Access Token to make your API calls
anchorRegistering your Integration
anchor

Registering an integration with Webex Teams is super easy. If you're logged in, select My Webex Teams Apps from the menu under your avatar at the top of this page, click "Create a New App" then "Create an Integration" to start the wizard. You'll need to provide some basic information like your integration's name, description, and logo. This information should be user-facing since that's what they'll see in the permission dialog.

After successful registration you'll be taken to a different screen containing your integration's newly created Client ID and Client Secret. The Client Secret will only be shown once so please copy and keep it safe!

anchorRequesting Permission
anchor

This step requires that your integration have a user interface capable of temporarily sending users to a Webex Teams login page. For web apps this is typically done as a popup or redirect. For mobile apps consider using a "WebView" or equivalent on your mobile platform of choice.

To kick off the flow send your user to the following URL along with a standard set of OAuth query parameters:

https://api.ciscospark.com/v1/authorize

The required query parameters are:

Query ParameterValue
response_typeMust be set to "code"
client_idIssued when creating your app
redirect_uriMust match one of the URIs provided during integration registration
scopeA space-separated list of scopes being requested by your integration (see below)
stateA unique string that will be passed back to your integration upon completion (see below)

After logging in, users will see a grant dialog like this one:

anchorScopes
anchor

Scopes define the level of access that your integration requires. The following is a complete list of scopes and their user-facing descriptions as shown in the permission dialog.

Scope
Usage
spark:all
Full access to your Webex Teams account
spark:memberships_read
List people in the rooms you are in
spark:memberships_write
Invite people to rooms on your behalf
spark:messages_read
Read the content of rooms that you are in
spark:messages_write
Post and delete messages on your behalf
spark:people_read
Read your users' company directory
spark:rooms_read
List the titles of rooms that you are in
spark:rooms_write
Manage rooms on your behalf
spark:team_memberships_read
List the people in the teams your user belongs to
spark:team_memberships_write
Add people to teams on your users' behalf
spark:teams_read
List the teams your user's a member of
spark:teams_write
Create teams on your users' behalf
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: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-compliance:events_read
Access to read events in your user's organization
spark-compliance:memberships_read
Access to read memberships in your user's organization
spark-compliance:memberships_write
Access to create/update/delete memberships in your user's organization
spark-compliance:messages_read
Access to read messages in your user's organization
spark-compliance:messages_write
Post and delete messages in all spaces in your user's organization
spark-compliance:rooms_read
Access to read rooms in your user's organization
spark-compliance:team_memberships_read
Access to read team memberships in your user's organization
spark-compliance:team_memberships_write
Access to update team memberships in your user's organization
spark-compliance:teams_read
Access to read teams in your user's organization

Scopes that begin with spark-admin can only be granted to users with administration access in their organization. Granting this scope to non-admin users will not allow your application to perform these actions.

The spark:all scope acts as an overall aggregate for the rest of the user scopes. It requests full access to a Webex Teams account. It does not include any spark-admin scope privileges, which may be added if necessary. This special scope allows your application to behave as a native Webex Teams client, providing access to all privileges for a Webex Teams account. Applications that use the Webex Teams SDKs to enable calling features will require the spark:all scope.

As a general best practice, your integration should request only the scope, or scopes, it needs. For example, if you are creating an integration that notifies users of updates in a third-party service, and never responds to any commands, we recommend using only the spark:messages_write scope.

State

The state parameter is used to verify that the response from grant flow has not been tampered with along the way. It is recommended that your integration set this to a value that is verifiable once the user gives permission and the web browser is sent to your redirect_uri. A second use for this parameter is to encode basic state information like an internal user ID or the URL of the last page they were on before entering the grant flow.

anchorGetting an Access Token
anchor

If the user granted permission to your integration, Webex Teams will redirect the user's web browser to the redirect_uri you specified when entering the grant flow. The request to the redirect URL will contain a code parameter in the query string like so:

http://your-server.com/auth?code=YjAzYzgyNDYtZTE3YS00OWZkLTg2YTgtNDc3Zjg4YzFiZDlkNTRlN2FhMjMtYzUz

Your integration will then need to exchange this Authorization Code for an Access Token that can be used to invoke the APIs. To do this your app will need to perform an HTTP POST to the following URL with a standard set of OAuth parameters. This endpoint will only accept a message body encoded with the application/x-www-form-urlencoded content type.

https://api.ciscospark.com/v1/access_token

The required parameters are:

ParameterValue
grant_typeThis should be set to "authorization_code"
client_idIssued when creating your integration
client_secretRemember this guy? You kept it safe somewhere when creating your integration
codeThe Authorization Code from the previous step
redirect_uriMust match the one used in the previous step

Webex Teams will then respond with JSON containing an Access Token that's good for 14 days and a Refresh Token that expires in 90 days, as shown in the example below:

{
 "access_token":"ZDI3MGEyYzQtNmFlNS00NDNhLWFlNzAtZGVjNjE0MGU1OGZmZWNmZDEwN2ItYTU3",
 "expires_in":1209600, //seconds
 "refresh_token":"MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTEyMzQ1Njc4",
 "refresh_token_expires_in":7776000 //seconds
}

After the access token expires, using it to make a request from the API will result in an "Invalid Token Error." At this point, you should use the refresh token to generate a new access token from the authorization server.

Using the Refresh Token

Using access tokens that are short-lived and requiring that they periodically be refreshed helps to keep data secure. If the access token is ever compromised, the attacker will have a limited time in which to use it. If a refresh token is compromised, it is useless to the attacker because the client ID and secret are also required to obtain a new access token.

To refresh the access token, issue a POST to https://api.ciscospark.com/v1/access_token with the following fields:

FieldValue
grant_typeThis should be set to "refresh_token"
client_idIssued when creating your integration
client_secretRemember this guy? You kept it safe somewhere when creating your integration
refresh_tokenThe Refresh Token you received from the previous step

Webex Teams will then respond with JSON containing a new Access Token. Generating a new Access Token automatically renews the lifetime of your Refresh Token.

Refreshing an access token before its expiration date will not cause the original access token to expire.

anchorInvoking the Webex Teams APIs
anchor

Authenticating with another user's Access Token works just like your developer token; supply the token in an Authorization header like so:

GET /rooms
Authorization: Bearer THE_ACCESS_TOKEN
Accept: application/json

or in cURL it would be

curl https://api.ciscospark.com/v1/rooms \
-H "Authorization: Bearer THE_ACCESS_TOKEN" \
-H "Accept: application/json"

The Bearer part is important as it instructs Webex Teams that this is an OAuth token instead of HTTP Basic Auth.

Last updated: November 8, 2018