Credentials

This guide describes how to obtain and use credentials for calling Bandwidth APIs.

API User Credentials

⚠️ The API user is meant to be separate from your App user and cannot be used to access the App. Further, your Dashboard user cannot be used to access Bandwidth's APIs.

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

Creating an API User

Bandwidth provides a 'user-based' permission and authentication scheme. It is required to use an API-only user. If you have not done so, please create a new user while following the directions for Allow user credentials to authenticate API. Assign only the necessary roles on your user. The API user can be leveraged to access all of Bandwidth's APIs.

⚠️ Usernames and Passwords are case-sensitive!

Credentials Snapshot

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

Creating an API User

Bandwidth provides a 'user-based' permission and authentication scheme. It is required to use an API-only user. If you have not done so, please create a new user while following the directions for Allow user credentials to authenticate API. Assign only the necessary roles on your user. The API user can be leveraged to access all of Bandwidth's APIs.

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}
• 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

Our Bearer tokens can be obtained from our OAuth provider. The token will contain the permissions for your set of credentials and can be used to call all of the APIs that denote they support the Bearer token Authentication scheme.

caution

The token should be retrieved from a server running in a secure environment and securely provided to clients. Client-side javascript does not have a mechanism for hiding these credentials so DO NOT place these directly in your client-side code.

Bandwidth accepts no responsibility for the loss of account credentials and any resulting network traffic, fraud, or undesired account access that results from failing to manage account access credentials in a completely secure manner.

The process to retrieve an access token requires you to have your ClientID and ClientSecret which you generated in the UI. You will then make a call to our token endpoint with these credentials. We will then return to you an access_token, id_token, token_type, and expires_in (this is the number of seconds before the token will expire).

Request

In order to retrieve the token, you will use Basic Authentication ClientID:ClientSecret. Below is 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

Now that we've shown the request, let's break down the parts of the API call.

• url https://id.bandwidth.com/api/v1/oauth2/token
• Headers
  • Authorization - Authentication is required. You MUST provide your ClientID and ClientSecret using a Base64-encoded header with the Basic authentication scheme. The header value before encoding should take the form Basic <ClientID>:<ClientSecret>.
  • Content-Type - You MUST use application/x-www-form-urlencoded. The parameters need to be converted key=value pairs which are separated by an ampersand &. Keys and values need to be URL encode (aka percent-encode).
• Body
  • grant_type Currently, we only support client_credentials OAuth2 grant_type.

Response

A sample response is:

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

Let's see what each item in the response object is meant for:

• access_token: This is the JSON Web Token (JWT) that will be passed in the Authorization header of the requests to the In-App Calling API. NOTE: The example above does not contain a valid token and cannot be used to actually authenticate.
• access_token_id: This will be the ID of the access token to prevent tokens from being re-used. It will be the same as the jti claim within the access token.
• token_type: This is used to identify the type of token and also the prefix to be used in the Authorization header.
• expires_in: This is the length of time, in seconds, before a token expires. In the example above the value is 3600. This means the token will be valid for 3600 seconds (1 hour) before it expires. You should use the token until 5-10 seconds before expiration, at which point you MUST request a new token in the same manner as described above.

Basic Authentication

For Bandwidth's APIs that do not authenticate with Bearer Authentication, use Basic Authentication over HTTPS. Basic Authentication requires the user's username:password pair to be encoded with Base64 as part of the Authorization HTTP header.