Credential Management

This guide provides an overview of how to manage your Bandwidth API credentials, including creating, using, rotating, updating, and revoking them.

Creating API Credentials

You can create API credentials via the Bandwidth App or the API.

Via the Bandwidth App

1. Log in to the Bandwidth App.
2. Navigate to Account > API Credentials.
3. Click on the Create button.
4. Fill in all required fields:
   • Description: A brief note to help you identify these credentials.
   • Account scope: Choose whether the credentials will have basic or admin level access.
   • Expiration: Optionally set an expiration date for the initial client secret.
   • Roles: Select the roles that define the permissions for these credentials.
   • Accounts: Select the accounts that these credentials will have access to.
5. Click Create to generate your new API Credential.

warning

Client Secret Notice: Make sure to securely store the Client Secret, as it will only be shown once.

Via the API

See our API Reference for detailed information on creating credentials via the API.

You will need to call the following endpoints:

POSThttps://api.bandwidth.com/api/v1/credentials

Sample Request Body:

{
  "description": "My API Credential",
  "accountScope": "ACCOUNT",
  "roles": ["Porting"],
  "accounts": ["123456"]
}

Create a new API credential. You will receive the clientId in the response.

POSThttps://api.bandwidth.com/api/v1/credentials/{clientId}/secrets

Sample Request Body:

{
  "expirationDate": "2026-12-31T23:59:59Z"
}

Create a new client secret for the credential. You will receive the clientSecret in the response.

warning

Client Secret Notice: Make sure to securely store the Client Secret, as it will only be shown once.

Using API Credentials

warning

Security Notice: Always retrieve tokens from a server running in a secure environment and provide them securely to clients. Client-side JavaScript does not have a mechanism for hiding credentials, so DO NOT place credentials directly in your client-side code.

Bandwidth accepts no responsibility for lost account credentials or any resulting network traffic, fraud, or unauthorized account access resulting from failing to manage account credentials securely.

Bandwidth SDKs

Using Bandwidth SDKs

Newer versions of the Bandwidth SDKs handle the OAuth 2.0 Client Credentials flow for you. When initializing the SDK, provide your Client ID and Client Secret, and the SDK will manage token retrieval and refreshing automatically.

Upgrade to the latest version of the Bandwidth SDK for your programming language and refer to the SDK documentation for specific instructions on how to use API Credentials.

Custom HTTP

OAuth 2.0 Client Credentials Flow

To authenticate API requests using your API credentials, you will need to obtain a Bearer token via the OAuth 2.0 Client Credentials flow. Several libraries exist to help with this process in various programming languages, or you can implement the flow manually using HTTP requests.

Request

To retrieve a token, use Basic Authentication with your Client ID:Client Secret. Here's a sample request:

curl --request POST \
--url https://api.bandwidth.com/api/v1/oauth2/token \
--header 'Authorization: Basic amRvZTpjb3JyZWN0LWhvcnNlLWJhdHRlcnktc3RhcGxl' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials

Let's break down the parts of this API call:

• URL: https://api.bandwidth.com/api/v1/oauth2/token
• Headers:
  • Authorization - You MUST provide your Client ID and Client Secret using a Base64-encoded header with the Basic authentication scheme. The header value before encoding should follow the format: <Client ID>:< Secret>.
  • Content-Type - You MUST use application/x-www-form-urlencoded. Parameters must be formatted as key=value pairs separated by an ampersand (&). Keys and values must be URL-encoded (also known as percent-encoded).
• Body:
  • grant_type - We only support the client_credentials OAuth 2.0 grant type.

Response

Here's a sample response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFsb2hvbW9yYSJ9.e30.kl3HYFQIcP4xZd78wUkdXxntxBu1d7b5ZCt99qVObC-gUZd5KSq2J7Q5rDb2LjP1_WVndcLQSqCoq3Anvp03hJWM6mamZL3dWHxjGLwkrIlzmNx9ZFGhTGIEsYLyaQqy8MonWYw2mJ4Z0APEfTVbTBHNIGrm_9GT6rIkdOwQFM-XgH1Tau4JbpFJun3n6o15WTgjzdEj9fIwd385CPwL-pAmOiozbYWUEzgqkXjSGHI11hiLDu-tv_8Ds06Cx4iCnL1F6_dFrnpD3CF0i6JJYVrvLmi6vgzoxp9YEIRBwaOZTSuYuYt03SQfbMZy8L2Z71sRKLLGt3TrxgtwyjefpQ",
  "access_token_id": "a5xA3xMKEggGwvpSLtk2lRb",
  "token_type": "Bearer",
  "expires_in": 3600
}

Here's what each field in the response means:

• access_token - The JSON Web Token (JWT) to pass in the Authorization header when making requests to Bandwidth APIs. Note: The example above does not contain a valid token and cannot be used for actual authentication.
• access_token_id - The unique identifier for the access token that prevents token reuse. This is the same as the jti claim within the access token.
• token_type - Identifies the type of token and the prefix to use in the Authorization header (e.g., "Bearer").
• expires_in - The time in seconds before the token expires. In this example, 3600 means the token is valid for 1 hour. You should use the token until 5-10 seconds before expiration, at which point you MUST request a new token using the same method described above.

Storing and Using the Token

After obtaining the access_token, include it in the Authorization header of your API requests as follows:

Authorization: Bearer {access_token}

The token is valid for the duration specified in the expires_in field. You should store and reuse your token for the duration of its lifetime. Ensure to refresh the token before it expires to maintain uninterrupted access to the Bandwidth APIs.

Rotating Your Client Secret

To enhance security, we recommend rotating your client secret periodically. You can do this via the Bandwidth App or the API. We support up to two active client secrets per API credential to facilitate smooth rotation.

warning

Client Secret Notice: Make sure to securely store any newly created Client Secrets, as they will only be shown once.

Via the Bandwidth App

1. Log in to the Bandwidth App.
2. Navigate to Account > API Credentials.
3. Select the API credential for which you want to rotate the client secret.
4. In the secrets section, click on Create New Secret.
5. Enter the expiration date for the new secret, if desired.
6. Click Create to generate the new client secret.
7. Update your applications to use the new client secret for authentication.
8. Optionally, you can revoke the old client secret once you've confirmed that your applications are functioning correctly with the new secret.

Via the API

See our API Reference for more information on rotating client secrets via the API. You will need to call the following endpoints:

POSThttps://api.bandwidth.com/api/v1/credentials/{clientId}/secrets

Sample Request Body:

{
  "expirationDate": "2026-12-31T23:59:59Z"
}

Create a new client secret for the credential. You will receive the clientSecret in the response. Make sure to securely store the client secret, as it will only be shown once.

GEThttps://api.bandwidth.com/api/v1/credentials/{clientId}

Retrieve information about your credential, including the list of existing client secrets (without the secret values) for the credential and identify the secretId of the old secret you wish to revoke.

DELETEhttps://api.bandwidth.com/api/v1/credentials/{clientId}/secrets/{secretId}

Revoke the old client secret once you've confirmed that your applications are functioning correctly with the new secret.

Updating API Credentials

You can update certain properties of your API credentials via the Bandwidth App or the API.

Via the Bandwidth App

1. Log in to the Bandwidth App.
2. Navigate to Account > API Credentials.
3. Select the API credential you wish to update.
4. Modify the desired fields, such as:

• Description: A brief note to help you identify these credentials.
• Account scope: Choose whether the credentials will have basic or admin level access.
• Roles: Select the roles that define the permissions for these credentials.
• Accounts: Select the accounts that these credentials will have access to.
• Status: Activate or deactivate the credential.

Via the API

See our API Reference for more information on updating credentials via the API. You will need to call the following endpoint: -

PATCHhttps://api.bandwidth.com/api/v1/credentials/{clientId}

Sample Request Body:

{
  "description": "Updated API Credential Description",
}

Update the desired fields of your API credential. - You can use this endpoint to modify fields such as description, accountScope, roles, accounts, and status.

Revoking API Credentials

You can revoke your API credentials via the Bandwidth App or the API. We support deactivating credentials to temporarily disable them without permanent deletion. We recommend deactivating credentials first to ensure that no active applications are using them before proceeding with permanent deletion.

Deactivating Credentials

Via the Bandwidth App

1. Log in to the Bandwidth App.
2. Navigate to Account > API Credentials.
3. Select the API credential you wish to deactivate.
4. Click on the Edit button in the Credential details section.
5. Change the Status to Inactive.
6. Click Save to apply the changes.

Via the API

See our API Reference for more information on deactivating credentials via the API. You will need to call the following endpoint: -

PATCHhttps://api.bandwidth.com/api/v1/credentials/{clientId}

Sample Request Body:

{
  "status": "INACTIVE"
}

Update the status field of your API credential to INACTIVE.

Deleting Credentials

warning

Permanent Deletion Notice: Deleting API credentials is a permanent action and cannot be undone. Ensure that the credentials are no longer in use before proceeding with deletion.

Via the Bandwidth App

1. Log in to the Bandwidth App.
2. Navigate to Account > API Credentials.
3. Select the API credential you wish to delete.
4. Click on the Delete button.
5. Confirm the deletion when prompted.

Via the API

See our API Reference for more information on deleting credentials via the API. You will need to call the following endpoint:

DELETEhttps://api.bandwidth.com/api/v1/credentials/{clientId}

Permanently deletes your API credential. This action cannot be undone, so ensure that the credential is no longer in use before proceeding.