Admin - Authentication | Webex for Developers

Admin

Authentication

In Getting Started we showed you just how easy it is to send messages using your own access token. But what if your app needs to send messages on behalf of someone else? That's where Integrations and OAuth come in.

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?

anchor

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:

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

anchor

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

anchor

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:


`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:

OAuth App Grant

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.

Scope

Usage

meeting:schedules_read

Retrieve your Webex meeting lists and details

meeting:schedules_write

Create, manage, or cancel your scheduled Webex meetings

meeting:recordings_read

Retrieve your Webex meeting recordings for playback

meeting:recordings_write

Manage or delete your meeting recordings for playback

meeting:preferences_read

Retrieve your Webex meeting preferences

meeting:preferences_write

Edit your Webex meeting preferences

meeting:controls_read

Read meeting control information for in-progress meetings

meeting:controls_write

Update meeting controls for in-progress meetings

meeting:participants_read

Read participant information from meetings

meeting:participants_write

Manage participants within meetings

meeting:admin_participants_read

Read participant information from meetings for all Webex users of your organization

spark-admin:telephony_config_read

Read and list telephony configuration

spark-admin:telephony_config_write

Create, edit and delete telephony configuration

meeting:admin_schedule_read

Retrieve meetings of all Webex users of your organization

meeting:admin_schedule_write

Create, manage, or cancel meetings of all Webex users of your organization

meeting:admin_recordings_read

Retrieve recordings of all Webex users of your organization

meeting:admin_recordings_write

Manage or delete recordings of all Webex users of your organization

meeting:admin_transcripts_read

Retrieve Webex meetings transcripts of all Webex users of your organization

meeting:admin_preferences_write

Manage meeting preferences of all Webex users of your organization

meeting:admin_preferences_read

Retrieve Webex meeting preferences of all Webex users of your organization

spark-compliance:meetings_read

Access to read recording and transcript resources in your user’s organization.

meeting:transcripts_read

Retrieve your Webex meetings transcripts

spark-compliance:meetings_write

Access to update/delete recordings and transcripts in your user’s organization.

spark-admin:workspace_locations_read

See details for your workspace locations

spark-admin:workspace_locations_write

Create, modify and delete your workspace locations

spark-admin:workspace_metrics_read

See metrics for your workspaces

identity:contacts_rw

Manage contacts.

identity:contacts_read

Read contacts.

spark:all

Full access to your Webex account

spark:webrtc_calling

Access webrtc services for Webex calling

spark:calls_read

List all active calls you are part of / List call history from Webex Calling

spark:devices_read

See details for your devices

spark:devices_write

Modify and delete your devices

spark:memberships_read

List people in the rooms you are in

spark:memberships_write

Invite people to rooms on your behalf

spark:messages_read

Read the content of rooms that you are in

spark:messages_write

Post and delete messages on your behalf

spark:organizations_read

Access to read your user's organizations

spark:people_read

Read your users' company directory

spark:places_read

See details for places and place services you manage

spark:places_write

Create, modify and delete places and place services you manage

spark:rooms_read

List the titles of rooms that you are in

spark:rooms_write

Manage rooms on your behalf

spark:team_memberships_read

List the people in the teams your user belongs to

spark:team_memberships_write

Add people to teams on your users' behalf

spark:teams_read

List the teams your user's a member of

spark:teams_write

Create teams on your users' behalf

spark-compliance:recordings_read

Access to read converged recording resources in your user’s organization.

spark-compliance:recordings_write

Access to update/delete converged recording resources in your user’s organization

spark:xapi_statuses

Retrieve all information from RoomOS-enabled devices.

spark:xapi_commands

Execute all commands on RoomOS-enabled devices.

spark:xsi

Access to your Webex Calling resources (e.g. calls & call settings)

spark-admin:devices_read

See details for any device in your organization

spark-admin:devices_write

Create, update and delete devices and device configurations in your organization

spark-admin:licenses_read

Access to read licenses available in your user's organizations

spark-admin:organizations_read

Access to read your user's organizations

spark-admin:people_read

Access to read your user's company directory

spark-admin:people_write

Access to write to your user's company directory

spark-admin:places_read

See details for any places and place service in your organization

spark-admin:places_write

Create, update and delete any place and place service in your organization

spark-admin:resource_group_memberships_read

Access to read your organization's resource group memberships

spark-admin:resource_group_memberships_write

Access to update your organization's resource group memberships

spark-admin:resource_groups_read

Access to read your organization's resource groups

spark-admin:roles_read

Access to read roles available in your user's organization

spark-admin:call_qualities_read

Access to read organization's call qualities

spark-admin:workspaces_read

See details for your workspaces

spark-admin:wholesale_sub_partners_read

Read or list sub-partners associated with a partner, subscribed to the Webex for Wholesale solution.

spark-admin:wholesale_sub_partners_write

Create or delete sub-partners associated with a partner, subscribed to the Webex for Wholesale solution.

spark-compliance:events_read

Access to read events in your user's organization

spark-compliance:memberships_read

Access to read memberships in your user's organization

spark-compliance:memberships_write

Access to create/update/delete memberships in your user's organization

spark-compliance:messages_read

Access to read messages in your user's organization

spark-compliance:messages_write

Delete messages in all spaces in your user's organization

spark-compliance:rooms_read

Access to read rooms in your user's organization

spark-compliance:rooms_write

Access to modify rooms in your user's organization

spark-compliance:team_memberships_read

Access to read team memberships in your user's organization

spark-compliance:team_memberships_write

Access to update team memberships in your user's organization

spark-compliance:teams_read

Access to read teams in your user's organization

spark-admin:broadworks_enterprises_read

Read or List BroadWorks Enterprise, provisioned as part of Webex for BroadWorks Solution.

identity:placeonetimepassword_create

Access to a one time password to a place to create an activation code

Identity:one_time_password

Request a one time password for people, devices, and things.

spark-compliance:webhooks_write

Delete org wide webhooks

spark-compliance:webhooks_read

Inspect org wide webhooks

spark:calls_write

Allow users to invoke call commands on themselves

spark-admin:hybrid_clusters_read

Access to read hybrid clusters for your organization

spark-admin:hybrid_connectors_read

Access to read hybrid connectors for your organization

spark-admin:broadworks_subscribers_read

Read or List BroadWorks Subscribers, provisioned as part of Webex for BroadWorks Solution.

spark-admin:broadworks_subscribers_write

Provision, Update or Remove a BroadWorks Subscriber as part of Webex for BroadWorks Solution.

audit:events_read

Access to the audit log for an organization

spark-admin:wholesale_customers_write

Provision, Update or Remove a Customer as part of Webex Wholesale Solution.

spark-admin:wholesale_customers_read

Read or List Customers, provisioned as part of Webex Wholesale Solution.

spark-admin:wholesale_subscribers_write

Provision, Update or Remove a Subscriber as part of Webex Wholesale Solution.

spark-admin:wholesale_subscribers_read

Read or List Subscribers, provisioned as part of Webex Wholesale Solution.

cjp:user

cjp:user

cjp:config_read

Read configurations details like teams, queue, sites, entry-points of your Contact Center

cjp:config_write

cjp:config_write

cjp:config

cjp:config

cloud-contact-center:pod_read

cloud-contact-center:pod_read

cloud-contact-center:pod_conv

cloud-contact-center:pod_conv

identity:groups_rw

Read Write groups

identity:groups_read

Read group

guest-issuer:read

Retrieve guest and guest metadata via Service App

guest-issuer:write

Create and manage guest users via Service App

spark:telephony_config_read

Read and list your telephony configuration

spark:telephony_config_write

Create, edit and delete your telephony configuration

spark-admin:locations_write

Create and edit location configuration.

identity:tokens_read

Admin can list token Ids for a user

identity:tokens_write

Admin can delete token for a user

meeting:admin_config_read

Retrieve Webex meeting configurations as an administrator

meeting:admin_config_write

Manage Webex meeting configurations as an administrator

spark-admin:locations_read

Read and list location configuration.

spark-admin:datasource_write

Allows a Service App to create new datasources and update existing datasources.

spark-admin:datasource_read

Allows a Service App to read datasources.

spark:applications_token

Retrieve Service App token. Not for FedRAMP customers.

application:webhooks_write

application:webhooks_read

List webhooks for Service App authorization. Not for FedRAMP customers.

spark-admin:metrics_read

Retrieve Webex metrics

guest-meeting:rw

Ability to orchestrate guest-to-guest meetings via Service App

webexsquare:get_conversation

Access Directory Search Service endpoints

dedicated-instance-uc:admin_perfmon_read

spark-admin:recordings_read

Read access to converged recording resources for admins in your user's organization.

spark-admin:recordings_write

Update and delete access to converged recording resources for admins in your user's organization.

spark:recordings_read

Read access to converged recordings for recording owners.

spark:recordings_write

Updated and delete access to converged recordings for recording owners.

identity:organizations_read

Read an organizations data, like name

identity:organizations_rw

Modify organizations data like name

spark-admin:telephony_pstn_write

Scope to limit the write access for partner telephony PSTN

spark-admin:telephony_pstn_read

Scope to limit the read access for partner telephony PSTN

spark-admin:broadworks_enterprises_write

Change BroadWorks Enterprise configuration, provisioned as part of Webex for BroadWorks Solution.

anchorGetting an Access Token

anchor

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:


`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

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:


`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

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

Note: Refreshing an access token before its expiration date will not cause the original access token to expire.

anchorInvoking the Webex APIs

anchor

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.