Webex Meetings Integrations

A Webex Meetings integration allows your application to authenticate XML API requests using OAuth 2.0 access tokens. This authentication method does require end user authorization and authentication, and is best used when performing API functions on behalf of the active user. If you require a system account to perform administrative functions on behalf of host users, you should use an alternate authentication method

With the EOL of the Webex XML APIs on March 31, 2024 the creation of Webex XML integrations via the developer.cisco.com integrations page page is now deprecated.
New integrations for Webex meetings XML APIs can be created on developer.webex.com (see Integrations). Please ensure the spark:all scope is selected. If you require access to your integrations that were created on developer.cisco.com, please open a Webex Developer Support ticket.

Scopes

Scopes represent available user privileges that your application can perform on a user's behalf. When you create your integration, you will need to select the available scopes that your application will need. Users will be prompted to allow or deny your application access to these privileges, so it is best to follow the principal of least privilege and only request those scopes that are needed by your application

Scope Usage
all_read Read-only privilege to access all Webex resources available to the authenticated user
user_modify Write-only privilege to update user details
meeting_modify Write-only privilege to create and update scheduled meetings
recording_modify Write-only privilege to update recorded meeting details
setting_modify Write-only privilege to update site settings. Admin only

Authorization

The first step in the OAuth 2.0 authentication flow is authorization. A user will be prompted with the scopes that you are requesting, and will have an opportunity to allow or deny access to thier account

Request Parameters

Query Parameter Value
response_type Should be code to return an authorization code
client_id System generated value provided by Webex when you create your Webex integration
redirect_uri Webex will redirect users to this URL when they authorize your integration to act on their behalf. Must match a redirect URI defined in your Webex Meetings Integration configuration
scope A set of one or more privileges that your application is requesting. Multiple scopes separated by +
state A unique string of your choosing. Matching string will be sent to your redirect_uri after authorization for tracking or validation
code_challenge A made up value, used for security purposes, that must match in future steps. Up to 10 characters
code_challenge_method Should be plain for plain text

Response

When a user authorizes access to their account, Webex will redirect the web browser to the redirect URI that was specified in the authorization step. Response will include the following parameters

Query Parameter Value
code An authorization code to be used in the authentication step
state Webex will return the same string that was set in the authorization request

Authentication

Authentication is used to generate an access token that can be used during XML API authentication.

Request Parameters

Query Parameter Value
grant_type Should be authorization_code or refresh_token
client_id System generated value provided by Webex when you create your Webex integration
client_secret System generated value provided by Webex when you create your Webex integration
code The authorization code provided in the authorization step. Used when grant_type is set to authorization_code
refresh_token Refresh token from a previous authentication, used to refresh an access token when it has expired. Used when grant_type is set to refresh_token
redirect_uri Must match a redirect URI defined in your Webex Meetings Integration configuration
code_verifier Must match the code used in the authorization step

Response

When a user has successfully authenticated, or when your application successfully refreshes an access token, Webex will respond with JSON code that includes the following information

Parameter Value
access_token Used to authenticate XML API requests. Added to the <webExAccessToken> element inside of <securityContext>. Valid for 2 hours
token_type Should be bearer
refresh_token Used to refresh user authentication after access_token has expired. Valid for 60 days. Should be prepended with the user's Webex site name followed by an underscore
expires_in access_token time to live in seconds. 2 hours
scope List of scopes the user has granted your application
user_name The user's Webex username
iss Token issuer. Can be ignored. Subdomain should match the user's Webex site name
siteid The user's Webex site ID. Can be ignored
userid Numerical user ID. Can be ignored
authentication_id Authentication ID. Can be ignored
email The user's Webex account email address