Webex Authentication
using Service App

In previous examples, you used a Personal Access token for all Webex API access. These tokens are great for quick testing, but they are not suitable for production applications because they are only valid for 12 hours. There are several other ways to obtain tokens for use in a production application. Which one you use depends on whose identity and permissions you want to use when interfacing with the API. The following are the different token types available for use in Webex APIs:

  • Personal Access Token: This is what you have been using up to now. It is a 12-hour time-limited token that inherits all the permissions of the user who generated the access token.
  • Bot Token: A bot is an account that has its own independent identity and performs actions on its own behalf. Bots are limited in the permissions granted to them. They can send and receive messages in spaces like other users, but they cannot see messages in a space unless the message is directed to the bot with an @mention of the bot or in a 1:1 conversation with the bot. Bots have no administrative access and are only used for messaging as they have no calling or meeting permissions. You will create a bot using a bot token later in this lab. Bot tokens are generated when you create a bot on developer.webex.com. As of the time of this writing, bot tokens do not expire for all practical purposes (their expiry is 100 years). If you lose a bot token, you must re-generate a new one which will invalidate the old bot token and provide you with a new one.

    The identity of a bot token is always a user id you create in the @webex.bot domain, not your own company's domain. This means that the namespace for bots is global to all of Webex, so if you want to create a bot named, for example, "mybot@webex.bot" you can only do so if no one else has already created a bot with that name. The display name, however, can be anything you want and may overlap with another bot much in the same way that you can have two people named Chuck Robbins as long as they have diferent user IDs.
  • Integration Token: An integration uses the OAuth2 Grant Flow to ask a user to grant your application permission to perform actions on their behalf. You have likely experienced an OAuth2 grant flow on websites that ask for permission to read data from another website - for example, a financial aggregation site wanting you to grant permissions to view your credit card balance from your banking site without giving the financial aggregation site your banking login information. When you create an integration, you specify the scopes that the integration is requesting and that list is presented to the end-user so they know what permissions they are granting your application. Following the above example, the financial aggregation site should only be requesting access to read your account balance and perhaps transaction history, but should not have access to make changes to your account in any way, so they would request scopes from your bank that limit what they can do. It is up to your bank to define what those scopes are and every bank could potentially define scopes differently. An integration gives your application both an access token and what is known as a refresh token. The refresh token allows the application to obtain a new access token and refresh token before the access token expires. Like access tokens, refresh tokens have a lifetime as well, but their expiry is typically longer then that of an access token. In many implementations, requesting a new access token by using a refresh token resets the expiry of the refresh token. This means that as long as you keep using the refresh token periodically, you can stay authenticated indefinitely, provided that the refresh token does not have an absolute expiry date set by the service.
  • Service App Token: This token type is similar to an Integration in that you are granting the application permissions to perform actions defined through a set of scopes, but instead of impersonating a specific user, a service app token gives an applcation administrative access to a specific Webex organization after being granted permission by an administrative user in that organization. As long as a service app is authorized in a given organization, it continues to have access until revoked by an administrator. The access is not based on the specific person who granted the access, so its access is retained even if users leave the organiation. Behind the scenes, a service app creates a hidden machine account user associated with each organization who is granting access to the application and it is this hidden user's permissions that are being granted to the service app. Like an integration, a service app will obtain both an access token and a refresh token.
  • Guest Token: There are some occasions where you want to interact with a user who does not have a Webex account, for example to provide a mechanism for users to send messages from a website or have a video call using Webex with an external user and have this integrated into a web portal of some kind. Webex previously had special tokens called Guest Issuer Tokens to facilitate these use-cases, but now, there are special scopes (guest-issuer:write and guest-issuer:read) that allow a service app to generate tokens for guests. Webex also has a special license type that allows service apps to generate guest to guest meetings where all participants in the meeting are guests. This can be used to facilitate use cases like connecting a patient to a doctor - neither of which are licensed Webex users.
In the end, no matter which mechanism is used, your application ends up with an access token that it passes in the Authorization header of the request to provide the necessary authentication credentials needed to perform the task in the API call. The differences above are in how you obtain that token, how long it lasts, the user context under which the request is made, and what level of permissions you get with the token.

The following table summarizes the differences between the various token types available in Webex.

How to Get Identity Access Scope Validity
Personal Access Token developer.webex.com The user who generated the token All permissions available to the user who generated the token 12 hours
Integration OAuth2 Grant Flow (requires web server) A user who granted permissions to the integration application Scopes that were requested by the app and granted by the user 14 day access token + 90 day refresh token
Service App developer.webex.com + Control Hub Admin A machine account with access to a specific Webex org Scopes that were requested by the app and approved by an org administrator 14 day access token + 90 day refresh token
Bot developer.webex.com The bot’s own identity (<bot>@webex.bot) Limited permissions specific to bots 100 years
Guest Generated by a Service App Guest user Limited to specific guest permissions 18 days

Given the various token generation methods available in Webex, the most appropriate one to use for an application that needs to perform administrative actions in an automated fashion is a Service App. This allows the application to perform administrative tasks without being tied to a specific administrator user in the organization. If you were using an integration or a personal access token. the tokens assigned to the application would be tied to a specific user, so if that user were to leave the company, your application would break. By using a Service App, you remove this depedency. It also allows administrators to delegate only specific permissions (scopes) to the application instead of giving it full administrative permissions. So for example, if you want to build an application that provisions users, you could grant the service app only access to the user provisioning scopes. Similarly, if you wanted to build an application that only uses reporting APIs to run analytics on your Webex data, you could grant the service app only the reporting scopes.

In this section, you will create a service app and use it to obtain tokens that you can use to perform actions your user account does not have access to. Once you have these tokens you can use this for a variety of functions later in the lab. To do this, you will perform the following tasks:

  1. Create a Service App
  2. Generate a new Access Token from the Refresh Token

Start by creating a Service App.

Step 1 - Create a Service App

  1. Access the Webex API documentation home page at: https://developer.webex.com
  2. If necessary, click Log in at top right and sign in with the following credentials:
    • Email address: pod6wbxuser@collab-api.com
    • Password: C1sco.123
  3. Once logged in, click on your icon at the top right.
  4. Click My Webex Apps (There should not be any existing Bots or Integrations, but if there are any Bots, feel free to delete them.)
  5. Click Create a Service App (If another app already exists, you would need to click Create a New App first.)
  6. For the App name, enter Pod6 Test Service App
  7. Click on one of the Icon images for your Service App so that it is selected.
  8. In the Description paste the following text: Cisco Live 2025 LTRCOL-2574 Service App for Pod 6 (https://collabapilab.ciscolive.com)
  9. In the Contact Email field paste the following text: pod6wbxuser@collab-api.com . This email address is only used if submitting the Service App for approval in the Webex App Hub so that others outside of your organization can use the app.

  10. For Scopes check the following boxes. NOTE that many of the scope names are very similar. You can click to copy each of these from the list and then use the Find function in the browser to search for each scope in the list. When you are done, be sure to double-check that you have seven scopes selected and they match the ones on this list. Failure to select the correct scopes will lead to issues later when you try to use the tokens.
    • spark-admin:telephony_config_read
    • spark:calls_read
    • spark:people_read
    • spark:people_write
    • spark-admin:licenses_read
    • spark-admin:people_read
    • spark-admin:people_write
  11. At the bottom, click Add Service App.
  12. You should now see a Congratulations message and some details about the App. Below that, Click the button to Request admin authorization.

    .

  13. The Service has now been submitted for approval. Notify one of the lab proctors and they will approve the request with an administrator account.

    .

  14. Since you are not an administrator you cannot approve yourself, but here are the steps that an administrator takes to approve the request. First, an administrator logs into Webex Control Hub, navigates to the Service Apps tab of the Management > Apps section, selects the request, reviews the scopes to ensure they approve of the app, and then and selects "Authorized". You will not perform this step in the lab as you do not have the right level of permissions to approve service apps, but we are including it here as a reference.

    .

  15. Once authorization is complete, click the reload button in your browser to obtain the information needed to generate tokens in a test script in VS Code.

    .

  16. Click the Copy button next to the Client ID.
  17. Access your VS Code instance: https://dev1.pod6.col.lab:8443 and from the Explorer open service_app.py.
  18. Find and replace the ___PASTE_SERVICE_APP_CLIENT_ID___ text in between the quotes with your Client ID that you just copied:

  19. Navigate back to the Service App page and click Regenerate the client secret. When prompted "By regenerating your secret you will revoke your current secret. Are you sure?", click Yes
  20. Click the Copy button next to the new Client Secret.
  21. Access VS Code again and replace the ___PASTE_SERVICE_APP_CLIENT_SECRET___ text in between the quotes with the new Client Secret that you just created and copied:

  22. On the Service App page, in the Org Authorizations section, click the Authorized orgs drop-down and select LTRCOL-2574_DND.
  23. The Enter Client Secret box will appear and you can paste the previously copied client secret into this box and click Generate tokens

    .

  24. Two tokens are now displayed below, an access_token and a refresh_token. Copy the refresh_token.

    .

  25. Switch back to VS Code and replace the ___PASTE_SERVICE_APP_REFRESH_TOKEN___ text with the refresh token.

That was all the information needed from the Service App. The access_token that was generated is valid, of course, but we do not know exactly for how long. The refresh_token, on the other hand, can be used to generate another access token, which you will do in the sample code.

Step 2 - Generate a new Access Token from the Refresh Token

When your application requests a new access token, Webex will return a new access token, including its expiration time, as well as a refresh token, which may or may not differ from the one used in the request, and its expiration time.

Knowing the exact expiration time of the tokens will allow you to request new ones before they expire, keeping the application up and running.

  1. Access your VS Code instance: https://dev1.pod6.col.lab:8443 and from the Explorer open service_app.py.
  2. Add the following lines to construct the payload consisting of the previously supplied client_id, client_secret, and refresh_token and send a POST request with the data to the Webex access_token request location:

  3. The code following what you just pasted prints out the results and uses the new access token to query the users in order to validate the token. You can just run this example. Click the Run and Debug button in the left column.
  4. Once you click anywhere in list of "RUN AND DEBUG" configurations, You should see a predefined Configuration for running a python script named Python: service_app.py in the list. Make sure it is selected:

  5. Click the green Start Debugging button left of the Python: service_app.py text. Doing so launches a Terminal with the complete logging output at the bottom. You will see the new access_token; its expires_in value in seconds, so basically 14 days; the refresh_token; and its refresh_token_expires_in in seconds, or 90 days.

    The output includes that it was able to log in using the Service App access token and query users without encountering an authentication or permissions error

  6. Copy the entire access token under the Your new Service App access token is: text, as highlighted in the above picture.
  7. In VS Code, from the Explorer open wxc_enable_user.py in the examples folder, the file you began editing earlier.
  8. Locate the position near the top where you previously pasted your personal access token and replace that token with the Service app access token that you just copied. This new token will give your application administrative rights to change users, which is essential for the tasks that will follow.

Now that you have an access token with administrative rights, you can continue with enabling a user for Webex Calling.