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

You can manage your Webex Meetings integrations at https://developer.cisco.com/site/webex-integration

Note

This requires you to be logged in to Cisco DevNet (this site) using a Webex Meetings Site Admin account. The dialog prompt for logging in to DevNet has the option to Login with Webex Meetings, other log in options will not work for this purpose

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