> For the complete documentation index, see [llms.txt](https://help.highlight.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.highlight.net/device-setup/cisco-webex-bot-token-guide.md).

# Cisco Webex Bot Token Guide

{% file src="/files/lI5LyAcZOyEl3WP9ylbW" %}

## 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](#id-4.-grant-the-bot-access-to-devices-in-control-hub)).

## 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](https://developer.webex.com/)

### 3.1 Sign in to the Developer Portal

<figure><img src="/files/89euHSxDeMhDPfGTBXom" alt="Webex Developer Portal image"><figcaption></figcaption></figure>

Go to [https://developer.webex.com](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>.

<figure><img src="/files/8Srdh9fnNmLEK5y5o6e5" alt="Open new Bot form"><figcaption></figcaption></figure>

### 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.

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

When the form is complete, click **Add Bot**.

<figure><img src="/files/t04715vS3Q9e4TvpCLmX" alt=""><figcaption></figcaption></figure>

### 3.4 Copy and store the access token

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

{% hint style="warning" %}
**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).
{% endhint %}

<figure><img src="/files/zT9zvY4pXxDGRCMjvB2s" alt="Copy and store access token"><figcaption></figcaption></figure>

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

{% hint style="info" %}
Regenerating invalidates the previous token.
{% endhint %}

## 4. Grant the bot access to devices in Control Hub

{% hint style="warning" %}
**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.
{% endhint %}

Device access is managed in Webex Control Hub: [https://admin.webex.com](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](https://admin.webex.com/) and sign in with an administrator account.

<figure><img src="/files/evTtAILllAKISfAhXJoE" alt="Control Hub"><figcaption></figcaption></figure>

### 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**.

<figure><img src="/files/3uUiPQVkOHqQ3HLd2G2b" alt="Workspace list"><figcaption></figcaption></figure>

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**.

<figure><img src="/files/oFzTxDGD0NrgaoRGgr80" alt="Edit API access"><figcaption></figcaption></figure>

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.

<figure><img src="/files/PMUSizCMTeSYCByYYxl7" alt="Select bot"><figcaption></figcaption></figure>

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

<figure><img src="/files/hI0CNwMuJ7HZpqw02APY" alt="Access successfully added"><figcaption></figcaption></figure>

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**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.highlight.net/device-setup/cisco-webex-bot-token-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.