Cisco Webex Bot Token Guide

How to create a bot access token and grant that bot access to Cisco Webex room devices in Control Hub

575KB

Webex_Bot_Token_Guide-Jun26.pdf

PDF

Open

Before you start

Audience: MSP partners & resellers · Version: 1 · Date: 01 Jun 26 This guide covers creating a bot access token and granting that bot access to Webex room devices in Control Hub. You will need a Webex account in the same organisation as the devices you wish to monitor, and a Control Hub administrator to complete the device-grant step (Section 4).

1. Overview

A Webex bot is a special, non-human account that owns its own permanent access token. Highlight uses this token to authenticate to the Webex REST API and to read status from Webex room and desk devices.

There are two things to understand up front:

• Creating the bot generates the access token. This is done on the Webex Developer Portal and takes a couple of minutes.

• Granting device access is a separate step. A newly created bot can talk to the API, but it cannot see any devices until a Control Hub administrator explicitly grants it access. This is the step most often missed.

Why the bot method?

Unlike a personal access token (which expires after 12 hours), a bot token does not expire. It is the appropriate choice for an unattended, long-running integration such as Highlight.

2. Prerequisites

• A Webex account that belongs to the same organisation as the devices to be monitored. A bot can only ever access devices within its creator's organisation.

• Administrator access to Webex Control Hub (yours or a colleague's) to complete the device-grant step.

• A secure location (e.g. a password manager) to store the generated token. The token grants API access and must be treated as a secret.

3. Create the bot and generate the token

All of the following is done on the Webex Developer Portal: https://developer.webex.com

3.1 Sign in to the Developer Portal

Go to https://developer.webex.com and sign in with the Webex account described in the prerequisites.

3.2 Open the New Bot form

Click your avatar (top-right) and choose My Webex Apps.

Click Create a New App, then Create a Bot.

You can also go straight to the form at https://developer.webex.com/my-apps/new/bot.

3.3 Complete the registration form

Fill in the bot details. A clear, identifiable name helps administrators recognise the bot later when granting device access.

Field	Guidance
Bot name	A friendly display name, e.g. "Highlight Monitoring". This is what appears in Webex spaces and in Control Hub.
Bot username	A unique username. Webex automatically appends @webex.bot. Choose something recognisable, e.g. highlight-monitoring.
Icon	Upload an icon or pick a default. Required to submit the form.
Description	A short description of the bot's purpose, e.g. "Reads device status for Highlight monitoring."

When the form is complete, click Add Bot.

3.4 Copy and store the access token

After clicking Add Bot, Webex displays a confirmation page that includes the bot's access token.

Important – the token is shown only once

Scroll down on the confirmation page to find the token, then copy it and store it securely before leaving the page. For security, the full token is displayed only at creation time. If you lose it, you cannot retrieve it — you must generate a new one (see below).

Lost the token? Open My Webex Apps, select the bot, and click Regenerate Access Token.

Regenerating invalidates the previous token.

4. Grant the bot access to devices in Control Hub

This step is required

A bot can authenticate to the API as soon as it is created, but it will return no devices until a Control Hub administrator grants it access. Until this is done, Highlight will not be able to read any device status.

Device access is managed in Webex Control Hub: https://admin.webex.com. This step must be performed by a Control Hub administrator for the organisation that owns the devices.

4.1 Sign in to Control Hub

Go to https://admin.webex.com and sign in with an administrator account.

4.2 Open the Workspaces area and grant access

Within Control Hub, navigate to the Workspaces section. In the left-hand menu, select Management → Workspaces.

4.2.1 Locate the Workspace you want to monitor the devices within, and click on it.

4.2.2 Scroll down to the devices panel, click the ellipses button in the top right, then click Edit API Access.

4.2.3 In the Device API access window, click Add user or bot. Click the Select user or bot drop-down and type the name of your bot in the search panel.

4.2.4 Select the bot, then click the access level drop-down and select Read Only. You should now see Access successfully added.

4.2.5 Repeat this process for each workspace whose devices you require to be monitored.

5. Create the controller in Highlight

Follow the steps at https://support.highlight.net/help/admin/sdwan_controllers to add a new Controller and select type: Cisco Webex.