Legacy Credentials

warning

Deprecation Notice: API Users are deprecated and will be removed in a future release. All users must migrate to OAuth 2.0 Client Credentials for API authentication. For more information, refer to our Credential Management Guide.

This guide describes how to obtain and use legacy credentials for authenticating with Bandwidth APIs.

API User Credentials

warning

API users are separate from your App users and cannot be used to access the App. Similarly, your Bandwidth App user cannot be used to access Bandwidth's APIs.

Creating an API User

Bandwidth uses a user-based permission and authentication scheme. You must create an API-only user to access the APIs. If you haven't done so yet, create a new user and follow the directions for Allow user credentials to authenticate API. Assign only the necessary roles to your user. This API user can be used to access all of Bandwidth's APIs.

Credentials Snapshot

Credential Name	Description	Example
username	Your API user's username	jdoe
password	Your API user's password	correct-horse-battery-staple

⚠️ Usernames and passwords are case-sensitive!

Unlike other user types, an API user is not required to update their password.

note

By default, users with no assigned role(s) will have the ability to perform GET requests against the following endpoints:

• Orders:
  • https://api.bandwidth.com/api/accounts/{accountId}/orders
• Order Details:
  • https://api.bandwidth.com/api/accounts/{accountId}/orders/{orderId}
• Location (SIP Peer) Details:
  • https://api.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers
• Admin Edge Settings:
  • https://api.bandwidth.com/api/accounts/{accountId}/products/edgemanagement/settings
• Subscriptions API:
  • https://api.bandwidth.com/api/accounts/{accountId}/subscriptions

Bearer Authentication

Bearer tokens can be obtained from our OAuth provider. The token contains the permissions for your credentials and can be used to call any Bandwidth API that supports the bearer token authentication scheme.

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 these directly in your client-side code.

Bandwidth accepts no responsibility for lost account credentials or any resulting network traffic, fraud, or unauthorized account access that results from failing to manage account credentials in a secure manner.

To retrieve an access token, you need your Username and Password. Make a call to our token endpoint with these credentials, and you'll receive an access_token, access_token_id, token_type, and expires_in (the number of seconds before the token expires).

Request

To retrieve the token, use Basic Authentication with your Username:Password. Here's a sample request:

curl --request POST \
  --url https://id.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://id.bandwidth.com/api/v1/oauth2/token
• Headers:
  • Authorization - You MUST provide your Username and Password using a Base64-encoded header with the Basic authentication scheme. The header value before encoding should follow the format: <Username>:<Password>.
  • 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) that you'll 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, which 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.

Basic Authentication

For Bandwidth APIs that don't support Bearer Authentication, use Basic Authentication over HTTPS. Basic Authentication requires your username:password pair to be Base64-encoded and included in the Authorization HTTP header.