Bandwidth is retiring legacy API User authentication on December 2, 2026. If your Bandwidth inbox still uses an API Key and API Secret, migrate it to OAuth credentials by December 1, 2026 to keep messaging connected.

You can update credentials on your existing inbox. Your phone number, conversations, and message history stay in place. You do not need to delete or recreate the inbox.

## Before you begin

* You need administrator access to your Chatwoot account.

* You need access to API Credentials in your Bandwidth account. If this option is missing, ask your Bandwidth administrator to enable the Credential access role.

* For self-hosted installations, Bandwidth OAuth migration is available in Chatwoot 4.20 and later. Upgrade to version 4.20 or later before following these steps.

## 1. Create OAuth credentials in Bandwidth

1. Sign in to the Bandwidth App and open **Account → API Credentials**.

2. Select **Add Credential**. Choose the account and roles needed for your existing messaging integration, and set a secret expiration date appropriate for your team.

3. Save the credential, then copy the **Client ID** and **Client Secret**. Store the secret securely: Bandwidth only displays it once.

For provider instructions, see [Bandwidth’s API User Migration guide](https://dev.bandwidth.com/docs/account/credentials/migration/).

## 2. Update your existing inbox in Chatwoot

1. Open **Settings → Inboxes** and select your Bandwidth inbox.

2. Open the **Configuration** tab. You can also select **Update credentials** in the migration notice.

3. Check the saved **Account ID** and **Application ID**. These fields are read-only.

4. Enter the new **Client ID** and **Client Secret**.

5. Select **Verify and save credentials**.

Chatwoot verifies the credentials before saving them. After a successful update, the migration notice disappears and the Client Secret field clears. Your callback URL stays the same.

The Configuration tab for an existing Bandwidth inbox:

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSHJZWndjPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--476b4ffd866854ec29478a28ee32d480d6719da3/codex-clipboard-aa0fc37b-e383-48c2-b29d-880e3909bb4e.png)

## 3. Test messaging after migration

Credential verification confirms authentication. Before considering the migration complete:

* Send an SMS from the existing Chatwoot inbox and confirm it reaches the recipient.

* Reply from the recipient’s phone and confirm the message appears in the same inbox and conversation.

* If you use MMS, test sending and receiving a message with an attachment.

Repeat the update and messaging checks for every Bandwidth inbox that uses legacy credentials.

## If you cannot save the credentials

* **Credentials rejected:** Check that you entered the Client ID and Client Secret from API Credentials, rather than the legacy API Key and API Secret. Confirm the credential covers the correct account, has the required messaging access, and has an active secret.

* **Temporary provider error:** Try again when Bandwidth is available. An unsuccessful verification leaves your previously saved configuration unchanged.

* **Account ID or Application ID is incorrect:** Contact Chatwoot support before proceeding. Token verification alone does not confirm that these saved identifiers are correct.

* **Configuration tab or OAuth fields are missing:** On a self-hosted installation, update to Chatwoot 4.20 or later. Contact support if you use Chatwoot Cloud.

## What happens to legacy credentials?

Inboxes that have not been migrated continue using their saved legacy credentials until Bandwidth retires API User authentication. Once you save OAuth credentials, that inbox uses OAuth and does not fall back to legacy authentication.

Do not deactivate legacy API Users until you have verified every application and inbox that depends on them. Updating one Chatwoot inbox does not migrate other integrations using the same legacy credentials.

Bandwidth’s deadline and credential requirements are explained in [Creating and managing your Bandwidth API credentials](https://www.bandwidth.com/support/en/articles/13004306-creating-and-managing-your-bandwidth-api-credentials).