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 created when you create a bot on developer.webex.com.
As of the time of this writing, bot tokens essentially do not expire (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.
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 site like
Mint wanting you to grant permissions to view your credit card balance from your banking site without giving
Mint 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, Mint 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. Refresh tokens have a lifetime as well, but their expiry is 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.
Guest Issuer 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.
Guest issuer tokens use the JWT standard and rely on an OAuth2 flow to obtain an access token needed for use
in the API.
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.
In the end, no matter which mechanism is used, your application ends up with an access token that it passes in
the Authorization heder 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.
Given the various token generation methods available in Webex, the most appropriate one to use for an application like
the management portal you are building is a Service App .
This allows the application to perform administrative tasks without being tied to a specific administrator user in
the organization. It also allows administrators to delegate only specific permissions (scopes) to the application
instead of giving it full administrative permissions.
In this section, you will perform the following tasks:
Create a Service App
Generate a new Access Token from the Refresh Token
If necessary, click Log in at top right and sign in with the following credentials:
Email address:
pod6wbxuser@collab-api.com
Password:
C1sco.123
Once logged in, click on your
icon at the top right.
Click My Webex Apps (There should not be any existing Bots or Integrations, but if there are
any Bots, feel free to delete them.)
Click Create a Service App (If another app already exists,
you would need to click Create a New App first.)
For the App name, enter
Pod6 Test Service App
Click on one of the Icon images for your Service App so that it is selected.
In the Description paste the following text:
Cisco Live 2024 LTRCOL-2574 Lab Service App for Pod 6 (https://collabapilab.ciscolive.com)
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.
For Scopes check the following boxes:
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
At the bottom, click Add Service App.
You should now see a Congratulations message and some details about the App. Below that,
Click the button to Request admin authorization.
.
The Service has now been submitted for approval. Notify one of the lab proctors
and they will quickly approve the request.
.
For an administrator, this involves simply logging into Webex Control Hub, navigating to the
Service Apps tab of the Management > Apps section, selecting the request and Authorizing, after
reviewing the requested scopes. 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.
.
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.
.
Find and replace the ___PASTE_SERVICE_APP_CLIENT_ID___ text in between the quotes with
your Client ID that you just copied:
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
Click the Copy button next to the new Client Secret.
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:
On the Service App page, in the Org Authorizations section, click the
Authorized orgs drop-down and select LTRCOL-2574_DND.
The Enter Client Secret box will appear and you can paste the previously copied client secret
into this box and click Generate tokens.
Two tokens are now displayed below, an access_token and a refresh_token.
Copy the refresh_token.
.
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.
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:
The code following what you just pasted prints out the results and use the new access token to query the
users, as you did previously,
in order to validate the token. You can just run this example. Click the
Run and Debug button in the left column.
Make sure the preconfigured configuration for running this script, called
Python: service_app.py is selected:
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
Copy the entire access token under the Your new Service App access token is: text, as
highlighted in the above picture.
In VS Code, from the Explorer open wxc_enable_user.py in the
examples folder, the file you began editing earlier.
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.
icon at the top right.
.
.
.
.
.
.
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.
