How to configure Postman for Azure Digital Twins
This article describes how to configure the Postman REST client to interact with and test the Azure Digital Twins Management APIs. Specifically, it describes:
- How to configure an Azure Active Directory application to use the OAuth 2.0 implicit grant flow.
- How to use the Postman REST client to make token-bearing HTTP requests to your Management APIs.
- How to use Postman to make multipart POST requests to your Management APIs.
Get started on Azure Digital Twins by using a REST client tool such as Postman to prepare your local testing environment. The Postman client helps to quickly create complex HTTP requests. Download the desktop version of the Postman client by going to www.getpostman.com/apps.
Postman is a REST testing tool that locates key HTTP request functionalities into a useful desktop and plugin-based GUI.
Through the Postman client, solutions developers can specify the kind of HTTP request (POST, GET, UPDATE, PATCH, and DELETE), API endpoint to call, and use of SSL. Postman also supports adding HTTP request headers, parameters, form-data, and bodies.
Configure Azure Active Directory to use the OAuth 2.0 implicit grant flow
Configure your Azure Active Directory app to use the OAuth 2.0 implicit grant flow.
Open the API permissions pane for your app registration. Select Add a permission button. In the Request API permissions pane, select the APIs my organization uses tab, and then search for:
Azure Digital Twins. Select the Azure Digital Twins API.
Alternatively, search for
Azure Smart Spaces Service. Select the Azure Smart Spaces Service API.
The Azure AD API name and ID that will appear depends on your tenant:
- Test tenant and customer accounts should search for
Azure Digital Twins.
- Other Microsoft accounts should search for
Azure Smart Spaces Service.
The selected API shows up as Azure Digital Twins in the same Request API permissions pane. Select the Read (1) drop down, and then select Read.Write checkbox. Select the Add permissions button.
Depending on your organization's settings, you might need to take additional steps to grant admin access to this API. Contact your administrator for more information. Once the admin access is approved, the ADMIN CONSENT REQUIRED column in the API permissions pane will show similar to the following for your APIs:
Configure a second Redirect URI to
To make sure that the app is registered as a public client, open the Authentication pane for your app registration, and scroll down in that pane. In the Default client type section, choose Yes for Treat application as a public client, and hit Save.
Check Access tokens to enable the oauth2AllowImplicitFlow setting in your Manifest.json.
Copy and keep the Application ID of your Azure Active Directory app. It's used in the steps that follow.
Obtain an OAuth 2.0 token
In the examples below,
YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:
|YOUR_INSTANCE_NAME||The name of your Azure Digital Twins instance|
|YOUR_LOCATION||The region your instance is hosted on|
Set up and configure Postman to obtain an Azure Active Directory token. Afterwards, make an authenticated HTTP request to Azure Digital Twins using the acquired token:
Go to www.getpostman.com to download the app.
Verify that your Authorization URL is correct. It should take the format:
Name Replace with Example YOUR_AZURE_TENANT The name of your tenant or organization
Select the Authorization tab, select OAuth 2.0, and then select Get New Access Token.
Field Value Grant Type
Auth URL Use the Authorization URL from step 2 Client ID Use the Application ID for the Azure Active Directory app that was created or reused from the previous section Scope Leave blank State Leave blank Client Authentication
Send as Basic Auth header
The client should now appear as:
Select Request Token.
Scroll down, and select Use Token.
Make a multipart POST request
After completing the previous steps, configure Postman to make an authenticated HTTP multipart POST request:
Under the Headers tab, add an HTTP request header key Content-Type with value
Serialize non-text data into files. JSON data would be saved as a JSON file.
Under the Body tab, select
Add each file by assigning a key name, selecting
Then, select each file through the Choose File button.
- The Postman client does not require that multipart chunks have a manually assigned Content-Type or Content-Disposition.
- You do not need to specify those headers for each part.
- You must select
multipart/mixedor another appropriate Content-Type for the entire request.
Lastly, select Send to submit your multipart HTTP POST request. A status code of
201indicates a successful request. The appropriate response message will appear in the client interface.
Validate your HTTP POST request data by calling the API endpoint: