This repository offers a single Postman Collection across all Alexa Smart Properties Subscriptions and Regions to ease Developers with testing API calls from an already exiting REST Client. It can be used to troubleshoot API calls when coding to ensure format and payload are correct and can also be used as a standalone tool for getting and setting values on properties, units and settings
You need to have a valid Alexa Smart Properties Registration with at least one subscription enabled.
By the end of this Step, you would have Postman App (desktop or web) correctly configured on your machine.
Follow the instructions from the Postman Getting Started guide available here: https://learning.postman.com/docs/getting-started/installation-and-updates/
By the end of this Step, you would have defined a LWA Security Profile enabling calls to the ASP APIs using the LWA clientId and secret.
- Create a LWA Security Profile by following the steps in the LWA console, using the same Amazon Business account and email address that you registered with Alexa Smart Properties.
Ensure that you have entered a Consent Privacy Notice URL on your LWA Security Profile. This is mandatory to get access to some permissions scopes such as scopes linked to the Customer Profile Information.
- Define Allowed Return URLS on the Web Settings of your LWA Security Profile to use Postman to obtain an OAuth 2.0 token:
- https://oauth.pstmn.io/v1/browser-callback (for Postman Web App Usage)
- https://oauth.pstmn.io/v1/callback (For Postman Desktop App Usage)
- https://www.getpostman.com/oauth2/callback (for Postman Legacy Usage)
- https://www.postman.com/oauth2/callback (for Postman Legacy Usage)
- http://127.0.0.1:9090/cb (for Localhost Usage)
- Grant ASP APIs access to your LWA Client ID from the ASP Console Administration: US Console || CA Console || UK Console || FR Console || DE Console || IT Console || ES Console. Once your LWA Client ID would have been registered for API access, you would be able to obtain your ASP Organization identifier (
amzn1.alexa.unit.did.{id}).
By the end of this Step, you would have imported Postman Collection into your Postman app (desktop or web).
The different options to import data into Postman are documented here: https://learning.postman.com/docs/getting-started/importing-and-exporting-data.
Use the json file included in this repo as the collection you want to import.
Below you can find an illustration to import a Postman Collection from a file available on your filesystem into Postman Desktop App.
By the end of this Step, you would have defined all required Collection Variables to start performing API calls.
To be more flexible and reuse the same values accross multiple requests, Variables are used accross the Collection. Below you will find the different Variables you need to assign a Current Value:
| Variable | Current Value |
|---|---|
| Host | api.amazonalexa.com or api.eu.amazonalexa.com |
| ClientId | The Client ID from the Web Settings of your LWA Security Profile used to grant you API access from the ASP Console |
| ClientSecret | The Client Secret from the Web Settings of your LWA Security Profile used to grant you API access from the ASP Console |
| Scope | alexa::enterprise:management credential_locker::wifi_management profile:user_id |
| OrgId | The amzn1.alexa.unit.did.{id} you got once you have granted API access to your LWA Client ID from the ASP Console |
!!! Important !!! each time you update the value of a variable, you must save the changes. Otherwise, the new value won't be taken into account. Also, please note that if you change the LWA Scopes after generating a token, you will need to perform Step 5 below again.
For your information, the permission provided by each scope is detailed here:
alexa::enterprise:management: permission to get access to Alexa Management APIs. This basically covers APIs offers into all Alexa Smart Properties Subscriptions.credential_locker::wifi_management: permission to get access to Amazon Account Wifi Locker. This currently covers the API call to push a new Wifi Configuration on an Amazon Account (POST /credentiallocker/v2/saveWifiConfigurations).profile:user_id: permission to get access to Amazon Customer Profile Identifier. This currently covers the API call to get the principalId from an Amazon AccountGET /user/profile
Please note that the usage of Variables is not mandatory into Postman. You may decide afterwards to replace Variables usage from the original Collection by your own mean.
By the end of this Step, you would have configured a valid OAuth 2.0 Refresh Token on your Postman Collection to perform requests using the Postman Collection.
To call the APIs, you must include your API access token as part of the Authorization request header of each API call.
Access tokens will expire after a set time period (for a LWA access token, this is usually set to 60 minutes expiration). When you obtain an access token, you will also receive a refresh token. You can use a refresh token to retrieve a new access token.
Each Collection provided into this repository is embedding a "Pre-request Script" to manage for you the retrieval of a new access token from a refresh token.
All you have to do here is to obtain a Refresh Token directly from the Collection following the below instructions:
5.1. Locate the Authorization folder in the collection. We will use the "Authorization" tab from Postman to initiate the generation of an (Access, Refresh) token pair by hitting "Get New Access Token" button as shown below.
5.2 Once the Authorization process has been initiated from previous step, you would be requested to input your Amazon Account Credentials. Here, you will connect with the Amazon Account that is considered as the ASP Operator for programmatic access.
5.3 Into this step, you will confirm that you grant permission to use Alexa Management APIs, Credentials Locker APIs and Customer Profile User ID from the (Access, Refresh) token pair that will be generated.
Note: For the to Customer Profile User ID (the
user_idalso known asprincipalId), because no personal information is requested, the user will not be presented with a consent screen the first time they log in.
5.4 Once you would have consent to the permission, the Authorization Callback will bring you back to Postman where you will copy the Refresh Token (refresh_token) to register it into the Collection Variables
Note: To avoid mixing
access_tokenandrefresh_token, ensure that you copy the token starting withAtzr|...
5.5 To finalize the operation, you will paste the refresh_token value into the Collection Variable named RefreshToken
Note: Don't forget to save your variables collection after you have copy-paste the refresh token.
By the end of this Step, you would have validated that you can successfully perform API calls using this Postman Collection.
To ensure your Postman Collection is correctly configured, you can try the three below API calls and observe the typical expected output.
Important: Host for API Calls can differ from one country to another, please respect the below mapping:
| Service | North America Region | Europe Region |
|---|---|---|
| Countries | US, CA | UK, FR, DE, IT, ES |
| LWA | api.amazon.com | api.amazon.com |
| Alexa | api.amazonalexa.com | api.eu.amazonalexa.com |
| Credentials Locker | credential-locker-service.amazon.com | credential-locker-service.amazon.eu |
Login With Amazon
- Manage Authorization Code Grant from Login With Amazon
- Obtain Customer Profile Information from Login With Amazon
Alexa Smart Properties
- Hospitality REST API Reference
- Senior Living REST API Reference
- Healtcare REST API Reference
- PBX REST API Reference
Postman
This library is licensed under the Amazon Software License