Integrations & Authorization
Add features from third-party services to Webex or perform actions on behalf of another user with Integrations.
anchorWhat are Integrations?
anchorIntegrations are how you request permission to invoke the Webex REST API on behalf of another Webex user. To do this in a secure way the API supports the OAuth 2 standard which allows third-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 user, read on, we'll get you there in a few easy steps:
- Register your integration with Webex
- Request permission using an OAuth Grant Flow
- Exchange the resulting authorization code for an access token
- Use the access token to make your API calls
anchorRegistering your Integration
anchorRegistering 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!
Each Webex user account is limited to 20 integrations.
anchorRequesting Permission
anchorThis 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://api-usgov.webex.com/v1/authorize
The required query parameters are:
Query Parameter | Value |
---|---|
response_type | Must be set to "code" |
client_id | Issued when creating your app |
redirect_uri | Must match one of the URIs provided during integration registration |
scope | A space-separated list of scopes being requested by your integration (see below) |
state | A 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
anchorScopes 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.
meeting:schedules_read
meeting:schedules_write
meeting:recordings_read
meeting:recordings_write
meeting:preferences_read
meeting:preferences_write
meeting:controls_read
meeting:controls_write
meeting:participants_read
meeting:participants_write
meeting:admin_participants_read
spark-admin:telephony_config_read
spark-admin:telephony_config_write
meeting:admin_schedule_read
meeting:admin_schedule_write
meeting:admin_recordings_read
meeting:admin_recordings_write
meeting:admin_transcripts_read
meeting:admin_preferences_write
meeting:admin_preferences_read
spark-compliance:meetings_read
meeting:transcripts_read
spark-compliance:meetings_write
spark-admin:workspace_locations_read
spark-admin:workspace_locations_write
spark-admin:workspace_metrics_read
spark:all
spark:webrtc_calling
spark:calls_read
spark:devices_read
spark:devices_write
spark:memberships_read
spark:memberships_write
spark:messages_read
spark:messages_write
spark:organizations_read
spark:people_read
spark:places_read
spark:places_write
spark:rooms_read
spark:rooms_write
spark:team_memberships_read
spark:team_memberships_write
spark:teams_read
spark:teams_write
spark-compliance:recordings_read
spark-compliance:recordings_write
spark:xapi_statuses
spark:xapi_commands
spark:xsi
spark-admin:devices_read
spark-admin:devices_write
spark-admin:licenses_read
spark-admin:organizations_read
spark-admin:people_read
spark-admin:people_write
spark-admin:places_read
spark-admin:places_write
spark-admin:resource_group_memberships_read
spark-admin:resource_group_memberships_write
spark-admin:resource_groups_read
spark-admin:roles_read
spark-admin:call_qualities_read
spark-admin:workspaces_read
spark-admin:wholesale_sub_partners_read
spark-admin:wholesale_sub_partners_write
spark-compliance:events_read
spark-compliance:memberships_read
spark-compliance:memberships_write
spark-compliance:messages_read
spark-compliance:messages_write
spark-compliance:rooms_read
spark-compliance:rooms_write
spark-compliance:team_memberships_read
spark-compliance:team_memberships_write
spark-compliance:teams_read
spark-admin:broadworks_enterprises_read
identity:placeonetimepassword_create
Identity:one_time_password
spark-compliance:webhooks_write
spark-compliance:webhooks_read
spark:calls_write
spark-admin:hybrid_clusters_read
spark-admin:hybrid_connectors_read
spark-admin:broadworks_subscribers_read
spark-admin:broadworks_subscribers_write
audit:events_read
spark-admin:wholesale_customers_write
spark-admin:wholesale_customers_read
spark-admin:wholesale_subscribers_write
spark-admin:wholesale_subscribers_read
cjp:user
cjp:config_read
cjp:config_write
cjp:config
cloud-contact-center:pod_read
cloud-contact-center:pod_conv
identity:groups_rw
identity:groups_read
guest-issuer:read
guest-issuer:write
spark:telephony_config_read
spark:telephony_config_write
spark-admin:locations_write
identity:tokens_read
identity:tokens_write
meeting:admin_config_read
meeting:admin_config_write
spark-admin:locations_read
spark:applications_token
application:webhooks_write
application:webhooks_read
spark-admin:metrics_read
spark-admin:datasource_write
spark-admin:datasource_read
guest-meeting:rw
webexsquare:get_conversation
dedicated-instance-uc:admin_perfmon_read
spark-admin:recordings_read
spark-admin:recordings_write
spark:recordings_read
spark:recordings_write
identity:organizations_read
identity:organizations_rw
spark-admin:telephony_pstn_write
spark-admin:telephony_pstn_read
spark-admin:broadworks_enterprises_write
Scopes that begin with spark-admin
can only be used by users with administrative access to an organization. Requesting these scopes during a grant flow will not give non-admin users access to administrative functions.
The spark-compliance
scopes can only be used by an organization's compliance officers. See the Compliance Guide for more information.
The spark:all
scope grants access to certain Webex account features that are not granted via the other user-level scopes. Applications which use the Webex SDKs for calling features may require this scope. Most other applications will not need to use this scope. Consult the SDK documentation for information about whether your application will need to use this 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.
KMS Scope
After registering an integration, it will include the scopes you selected along with an additional scope: spark:kms
. This scope is required to give your integration permission to interact with encrypted content (such as messages). For convenience, the scope is included in the integrations's scope list in the example OAuth Authorization URL on the integration's application detail page. If you don't use the example URL, be sure to include the scope when creating authorization URLs for your integration.
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
anchorIf the user granted permission to your integration, the Webex REST API 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-usgov.webex.com/v1/access_token
The required parameters are:
Parameter | Value |
---|---|
grant_type | This should be set to "authorization_code" |
client_id | Issued when creating your integration |
client_secret | Remember this guy? You kept it safe somewhere when creating your integration |
code | The authorization code from the previous step |
redirect_uri | Must match the one used in the previous step |
The Webex REST API will then respond with JSON containing an access token and a refresh token, 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 HTTP 401 "Invalid Token Error" response, such as:
{
"message": "The request requires a valid access token set in the Authorization request header.",
"errors": [
{
"description": "The request requires a valid access token set in the Authorization request header."
}
],
"trackingId": "API_12345678-90AB-CDEF-1234-567890ABCDEF"
}
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-usgov.webex.com/v1/access_token
with the following fields:
Field | Value |
---|---|
grant_type | This should be set to "refresh_token" |
client_id | Issued when creating your integration |
client_secret | Remember this guy? You kept it safe somewhere when creating your integration |
refresh_token | The refresh token you received from the previous step |
The Webex REST API 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.
After the refresh token expires, using it to request a new access token from the API will result in an HTTP 400 "Invalid Request" response, such as:
{
"message": "The refresh token provided is expired, revoked, malformed, or invalid.",
"errors": [
{
"description": "The refresh token provided is expired, revoked, malformed, or invalid."
}
],
"trackingId": "API_12345678-90AB-CDEF-1234-567890ABCDEF"
}
anchorAccess Token Invalidation
anchorAn access token that's been issued to your app may be invalidated as a result of changes to a user's account. This includes, but is not limited to, the following scenarios:
- A user's account access changes as a result of updates to their email address or password.
- A user's Webex organization administrator deactivates and reactivates their account.
anchorInvoking the Webex REST API
anchorAuthenticating 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-usgov.webex.com/v1/rooms \
-H "Authorization: Bearer THE_ACCESS_TOKEN" \
-H "Accept: application/json"
The Bearer
part is important as it instructs the API that this is an OAuth token instead of HTTP Basic Auth.
With the API, you can perform actions as the user such as sending a message with an interactive card to someone. To respond to events, you'll need to configure webhooks. Webhooks will let your app know when an activity has occurred so you can take action. Check out the Webhooks Guide for more information about configuring webhooks.
With cards, you can give your users even more ways to interact with your integration or service, right in the Webex clients. See the Buttons and Cards Guide for more information.