Bandwidth’s APIs use Client Credentials (Client ID and Client Secret) for secure, machine-to-machine authentication via standard OAuth 2.0 flows. Client ID represents your application, while Client Secret is a private key used to prove your application’s identity. These credentials let your systems securely request short-lived access tokens to call Bandwidth APIs.
Create Client Credentials
Log in to the Bandwidth App.
In the side navigation bar, click Account and select API Credentials. Please note that you need to be an admin user or have the Credential Access Role enabled on your account to create new Client Credentials.
Click Add Credential and complete the following fields: Description, Account scope, Secret expiration date, Accounts (each credential must have at least one account), and Roles (each credential must have at least one role).
Click Save. The system will automatically generate and display your new Client ID and Client Secret.
Important: While your Client ID is always visible to you, your Client Secret will only be displayed once, so please make sure to copy and store it securely (e.g., in your organization’s credentials manager). Bandwidth cannot retrieve your Client Secret, so you’ll have to rotate it (create a new one) if it gets lost.
Manage Client Credentials
View existing credentials
You can view your existing Client IDs, including:
Creation dates
Associated roles and account scopes
Active Client Secrets (not the values themselves)
Rotate Client Secret
Rotating Client Secrets ensures continued security and uptime. To rotate Client Secret:
Select your Client ID and click Generate New Secret.
Update your application to use the new Client Secret.
Once confirmed working, delete the old Client Secret.
Each Client ID can have up to two active Client Secrets at a time. This allows a smooth transition during the rotation.
Delete Client Secret
Before deleting Client Secret, please verify that no systems are still using it. Deleted Client Secrets cannot be recovered.
Best practices
Never commit Client Secrets to source control or log files.
Rotate Client Secrets regularly (every 90 days is recommended).
Use separate Client IDs for development, staging, and production.
Store Client Secrets securely in a credential manager (e.g., vault, AWS Secrets Manager, Azure Key Vault).
Common scenarios
Scenario | What to do |
Lost Client Secret | Generate a new one and update your application. |
Expired/invalid token | Request a new token from our token endpoint using your current Client ID and Client Secret. |
Access Denied | Ensure your Client ID has the appropriate roles and account scopes. |
Need to delete test credentials | Navigate to the credentials list and remove the Client ID once it’s no longer needed. |
Frequently Asked Questions
How is an API credential different from an API user (Basic Authentication)?
Bandwidth API credentials use OAuth 2.0 client credentials for authentication rather than a static username and password. They generate short‑lived access tokens, offering stronger security, easier rotation, and modern compliance standards.
Can I continue using my existing API users?
Yes. Existing API users will continue to function until the Basic Authentication is retired on December 2, 2026.
Who can create API credentials?
Only admin users or users that have the Credential Access Role enabled on their account in the Bandwidth App can create or manage Client IDs and Client Secrets.
How many API credentials can I create?
There’s no hard limit for most accounts. However, we recommend creating separate credentials for each environment (development, staging, production) and use case to maintain clear separation of access.
What happens if I lose my Client Secret?
For security reasons, Bandwidth cannot retrieve a previously generated secret. If lost, please generate a new secret under the same Client ID, update your integrations to use the new value, and delete the old secret once validated.
How often should I rotate my Client Secret?
We recommend rotating Client Secrets every 90 days. Regular rotation helps maintain secure access and allows smooth transitions using dual‑active secret support.
Can I have multiple Client Secrets active at the same time?
Yes. Each Client ID supports two active Client Secrets simultaneously, allowing you to rotate them without downtime.
What environments or accounts can an API credential access?
When creating the credential, you’ll define account scope, roles, and permissions. Those selections control which accounts and APIs the credential can access.
How do I revoke or delete an API credential?
Navigate to the API Credentials section in the Bandwidth App, select the Client ID, and delete the credential or a specific Client Secret. Before deleting, please make sure your systems no longer use it, as deleted credentials cannot be recovered.
Does using API credentials change how I’m billed for API usage?
No. Authentication type doesn’t affect pricing or billing. API usage continues to be billed per Bandwidth’s standard API transaction model.
Where can I find technical documentation on using OAuth 2.0 with Bandwidth APIs?
You can find our complete developer documentation here.