Skip to main content

Postman

We recommend downloading, installing, and using Postman to test API requests and verify responses.

Set up Postman using OpenID Connect​

Prerequisites​

To use the Implicit grant type with your requests in Postman, you need to grant access to a multi-tenant app in Azure AD to use CDF with Postman. To grant access, you need to be an Azure AD tenant administrator.

Follow the steps in How to register Cognite API to register the app.

When you have registered the app, you will be able to sign in with your Azure AD credentials.

Step 1: Import your Postman collection​

  1. Download the Cognite OpenAPI specification. In Postman, select Import and drag the file to the import modal. You can choose how to import your API and manage the import settings in View Import Settings. In the Import Settings, set the Folder organization to Tags, select Enable optional parameters to turn it off, and select Always inherit authentication to turn it on. Select Import to import this data.

    Import Cognite API

  2. Select Continue > Import to import the collection.

Step 2: Set up environment variables​

  1. To create a new environment, navigate to Environments on the left sidebar. Click + Create new Environment and give it a name.

    Create environment

  2. Add the variables:

    • tenant-id: This is your Directory (tenant) ID. To find the tenant ID, go to your Azure Active Directory. You can find your Tenant ID on the Overview page.

      Tenant ID
      note

      We recommend that you work with the current value of a variable to prevent sharing sensitive and confidential information with your team.

    • token: Using OAuth 2.0, we will generate a new token. It will populate automatically, so you will leave it blank as an environment variable.

    • baseUrl: When you import the collection, the baseUrl is set to https://{{cluster}}.cognitedata.com/api/v1/projects/{{project}}. cluster is where your CDF instance is installed. If you don't know the cluster name, contact Cognite support.

    Note: For Open Industrial Data, the cluster is api.

    • project: This is your CDF project name.

      Project name

Step 3: Update authorization​

  1. To update the authorization, navigate to the Authorization tab in the collection overview.

  2. Select OAuth 2.0 as Type and Request Headers as Add auth data.

  3. Select Configure New Token and specify these configuration options:

    • Enter a Token Name.
    • Select the Grant Type as Implicit.
    • Input the Callback URL as https://postman.cogniteapp.com/loggedin.
    • Enter the Auth URL as https://login.microsoftonline.com/$tenant-id/oauth2/v2.0/authorize. Replace the tenant-id obtained from the previous step.
    • Input the Client ID as https://postman.cogniteapp.com.
    • The Scope is $baseUrl/$scope, where $baseUrl is as above in 2.2, and $scope is user_impersonation, DATA.VIEW, IDENTITY and more. user_impersonation grants all permissions to the user assigned to access the API. The DATA.VIEW scope grants read-only access to data in CDF, for example, to view files, time series, RAW, and other CDF resources. To know more about CDF's scopes, see the different Access token scopes.
    • Select Client Authentication as Send as Basic Auth header.
NOTE

If you don't select the checkbox Authorise using browser, you can input the Callback URL. Otherwise, the Callback URL gets auto-populated on selection. You will be redirected to the Callback URL once your application is authorized.

tip

While using a scope for the first time, the admin has to define the scope explicitly. The admin must then consent to use this scope for the authorization process.

OAuth 2.0 implicit
  1. Select Get New Access Token > Proceed > Use Token.

You are now ready to use Postman with OIDC as the authentication method.

Last updated