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 thespark:allscope 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
- Issue GET request to https://api.webex.com/v1/oauth2/authorize with the following URL encoded parameters
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.
- Issue a form encoded POST request to https://api.webex.com/v1/oauth2/token with the following parameters, Content-Type should be application/x-www-form-urlencoded
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 |