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.
By default, users with no assigned role(s) will have the ability to perform GET requests against the following endpoints:
- Orders:
https://dashboard.bandwidth.com/api/accounts/{accountId}/orders
- Order Details:
https://dashboard.bandwidth.com/api/accounts/{accountId}/orders/{orderId}
- SIP Peer Details:
https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers
- Admin Edge Settings:
https://dashboard.bandwidth.com/api/accounts/{accountId}/products/edgemanagement/settings
- Subscriptions API:
https://dashboard.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.
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
andClientSecret
using a Base64-encoded header with theBasic
authentication scheme. The header value before encoding should take the formBasic <ClientID>:<ClientSecret>
. - Content-Type - You MUST use
application/x-www-form-urlencoded
. The parameters need to be convertedkey=value
pairs which are separated by an ampersand&
. Keys and values need to be URL encode (aka percent-encode).
- Authorization - Authentication is required. You MUST provide your
- Body
grant_type
Currently, we only supportclient_credentials
OAuth2grant_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 thejti
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 is3600
. 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.