API User Migration

This guide provides an overview of how to migrate from Bandwidth's legacy API Users to the newer API Credentials system. API Credentials offer enhanced security and flexibility for authenticating and authorizing API requests.

Migrating from API Users to API Credentials

To migrate from API Users to API Credentials, follow these steps:

1. Create New API Credentials: Generate new API credentials in the Bandwidth App or via the API.
2. Update Your Application: Modify your application's code to use the new API credentials for authentication instead of the legacy API User credentials.
3. Test Your Integration: Ensure that your application functions correctly with the new API credentials.
4. Deactivate Legacy API Users: Once you have confirmed that everything is working as expected, you can deactivate your legacy API Users.

Creating New API Credentials

You can create and manage new API credentials via the Bandwidth App or the API. See our API Credentials Management guide for detailed instructions.

Updating Your Application Code

When updating your application code, replace any instances of the legacy API User Basic Authentication with new API Credentials handling the OAuth 2.0 Client Credentials flow.

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.

Testing Your Integration

After updating your application to use the new API credentials, thoroughly test all functionalities to ensure that everything works as expected.

Deactivating Legacy API Users

Once you have confirmed that your application is functioning correctly with the new API credentials, you can proceed to deactivate your legacy API Users to enhance security.

1. Log in to the Bandwidth App.
2. Navigate to the Users page.
3. Select the legacy API User you wish to deactivate.
4. Click on the "Deactivated" option.
5. Save your changes.

Congratulations! You have successfully migrated from API Users to API Credentials. For more information on our new credentials, refer to our API Credentials Management guide.