Keep in mind that you don't need to register an integration to explore the APIs. The best way to learn the APIs is to use your own personal access token to create rooms, play with messages, etc. If you're sure that your integrations require authenticating on behalf of another Webex user, read on.

anchorWhat are Integrations?

Integrations are how you request permission to invoke Webex APIs on behalf of another user. To do this in a secure way Webex 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.

We'll get you there in a few easy steps:

1. Register your integration with Webex
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

Registering an integration with Webex is super easy. If you're logged in, select My Webex 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

This step requires that your integration have a user interface capable of temporarily sending users to a Webex 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://webexapis.com/v1/authorize

The required query parameters are:

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

Scopes

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.

anchorGetting an Access Token

If the user granted permission to your integration, Webex 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 an x-www-form-urlencoded body.

https://webexapis.com/v1/access_token

The required parameters are:

Webex 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 tohttps://webexapis.com/v1/access_tokenwith the following fields:

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

anchorInvoking the Webex APIs

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://webexapis.com/v1/rooms \
-H "Authorization: Bearer THE_ACCESS_TOKEN" \
-H "Accept: application/json"

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