Authenticate to the Aware API
Configure HTTP Basic authentication and make your first Aware API request.
Aware uses HTTP Basic authentication for API requests. White Label Communications provides a username and password when API access is enabled.
This guide follows the command-line workflow demonstrated for the Aware API and ends with a GET request to retrieve the available device models.
Before you begin
You need:
- Access to Aware.
- API access enabled by White Label Communications. Contact your White Label Communications account representative to request access.
- The API username and password provided by White Label Communications.
- cURL to send the API requests.
jqto format the JSON responses shown in this guide.- Your Aware Customer Portal host.
The examples use a placeholder for your Aware Customer Portal host. Obtain the appropriate host for your environment before sending a request.
| Placeholder | Replace with |
|---|---|
<PORTAL_HOST> | Your Aware Customer Portal host. |
Replace the angle brackets and the text inside them. Do not send the placeholder as a literal value.
A few API basics
An API request is a message your application sends to Aware. The URL identifies the resource you want to access. The method describes the action; this guide uses GET to retrieve data. The response is the status and any data Aware sends back.
Aware API endpoints used in this guide are located under:
https://<PORTAL_HOST>/api/external/v1
How authentication works
The Aware API uses HTTP Basic authentication. Each API request includes the username and password provided by White Label Communications.
You do not need to create an API user or configure its permissions yourself. White Label Communications configures the user and its permitted access when your API access is provisioned.
Access tokens generated through the Aware Customer Portal are not used for these API requests.
Treat your API username and password as sensitive credentials. Store them securely and do not include them in public code, documentation, screenshots, or shell scripts that may be shared.
The environment variables used below are convenient for this walkthrough. Follow your organization's credential-management practices when building an integration.
Authenticate with HTTP Basic authentication
1. Request API access
Contact your White Label Communications account representative and request access to the Aware API.
White Label Communications will configure your access and provide you with:
- An API username.
- An API password.
No additional user configuration is required in Aware.
2. Set your credentials (optional)
For convenience, you can store the username and password provided by White Label Communications in environment variables:
export USER="YOUR_USERNAME"
export PASSWORD="YOUR_PASSWORD"
Replace YOUR_USERNAME and YOUR_PASSWORD with your API credentials.
This step is optional. Aware does not require your credentials to be stored as environment variables. This walkthrough uses $USER and $PASSWORD to make the example commands easier to read and to avoid retyping the credentials for each request.
You can use another secure method of supplying your credentials if preferred.
3. Make a successful GET request
Use the /node_models endpoint to retrieve the available device models.
Run:
curl -s --user "$USER:$PASSWORD" \
"https://<PORTAL_HOST>/api/external/v1/node_models" | jq
Replace <PORTAL_HOST> with your Aware Customer Portal host.
The command uses:
| Option | Purpose |
|---|---|
-s | Runs cURL in silent mode so progress information is not mixed with the API response. |
--user "$USER:$PASSWORD" | Sends the username and password using HTTP Basic authentication. |
jq | Formats the JSON response (piped from cURL) so it is easier to read. |
A successful request returns JSON containing the device models available through Aware. The exact models and values returned depend on your environment.
If the request returns 401 Unauthorized, verify the username and password and send the request again. If your credentials are correct and the request continues to return 401 Unauthorized, contact your White Label Communications account representative for assistance.
Once the /node_models GET request succeeds, you have authenticated to the Aware API and are ready to make additional API requests. Use the same Basic authentication credentials with each subsequent request.