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.

Postman summary

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.

  1. 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:

    1. Azure Digital Twins. Select the Azure Digital Twins API.

      Search API or Azure Digital Twins

    2. Alternatively, search for Azure Smart Spaces Service. Select the Azure Smart Spaces Service API.

      Search API for Azure Smart Spaces

    Important

    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.
  2. 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.

    Add API permissions for Azure Digital Twins

  3. 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 admin consent approval

  4. Configure a second Redirect URI to https://www.getpostman.com/oauth2/callback.

    Configure a new Postman Redirect URI

  5. 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.

    Public client configuration setting

  6. Copy and keep the Application ID of your Azure Active Directory app. It's used in the steps that follow.

    Azure Active Directory application ID

Obtain an OAuth 2.0 token

In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Name Replace with
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:

  1. Go to www.getpostman.com to download the app.

  2. Verify that your Authorization URL is correct. It should take the format:

    https://login.microsoftonline.com/YOUR_AZURE_TENANT.onmicrosoft.com/oauth2/authorize?resource=0b07f429-9f4b-4714-9392-cc5e8e80c8b0
    
    Name Replace with Example
    YOUR_AZURE_TENANT The name of your tenant or organization microsoft
  3. Select the Authorization tab, select OAuth 2.0, and then select Get New Access Token.

    Field Value
    Grant Type Implicit
    Callback URL https://www.getpostman.com/oauth2/callback
    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
  4. The client should now appear as:

    Postman client token example

  5. Select Request Token.

  6. 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:

  1. Under the Headers tab, add an HTTP request header key Content-Type with value multipart/mixed.

    Specify content type multipart/mixed

  2. Serialize non-text data into files. JSON data would be saved as a JSON file.

  3. Under the Body tab, select form-data.

  4. Add each file by assigning a key name, selecting File.

  5. Then, select each file through the Choose File button.

    Postman client form body example

    Note

    • 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/mixed or another appropriate Content-Type for the entire request.
  6. Lastly, select Send to submit your multipart HTTP POST request. A status code of 200 or 201 indicates a successful request. You will also see the appropriate response message.

Next steps