Postman

We recommend that you download, install and use 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. In Postman, select Import > Link and enter the URL to import your latest API V1 Postman collection: https://storage.googleapis.com/cognite-postman-collections/v1.json

   

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 side bar. Click + (Create new Environment) and give it a name.

   

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.

     

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

   • baseURL: You can find your baseURL from the CDF project. Navigate to your CDF project. Under Manage & Configure > Manage access, select Open ID connect tab. The URL in the audience field is the baseURL.

     

   • project: This is your CDF 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 to.

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.

     NOTE

     If you do not 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.

   • 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 IDENTITY, DATA.VIEW etc.

   • Select Client Authentication as Send as Basic Auth header.

     

4. Select Get New Access Token > Proceed > Use Token.

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

Set up Postman using API keys

Step 1: Import your Postman collection

In Postman, select Import > Import From Link and enter a URL to import one of our Postman collections:

API version	API Status	Postman collection link
API v1	Stable	Recommended for production environments. https://storage.googleapis.com/cognite-postman-collections/v1.json
Playground	Unstable	https://storage.googleapis.com/cognite-postman-collections/playground.json

Click Continue > Import. You have successfully imported the collection.

Step 2: Set up API keys and environment variables

Set the api-key and project environment variables. The api-key is injected as the header to authenticate your requests, and the project routes all your requests to the correct project in Cognite Data Fusion. To set the environment variables:

1. Click Environment quick look (eye) icon in the top-right corner. Click Add and enter an Environment Name, for example cognite-publicdata.

2. Under VARIABLE, enter api-key, and in the CURRENT_VALUE field enter your API key.

3. Add another VARIABLE, name it project, and in the CURRENT_VALUE field enter the name of your project.

   If you got your API key from the Open Industrial Data Project, enter publicdata as the name of the project.

4. Click Save to save the environment variables you have added.

5. If necessary, select your newly created environment in the dropdown menu in the top right corner.

   

Step 3: Send your API request

Make a test API request to check that your integration is working correctly:

1. Click the Cognite API collection in the left-hand menu, and select Assets > List assets.

   

2. Click Send.

Cognite Data Fusion returns a list of all asset objects in response to your API request. Once you have successfully made an API request, you’re ready to begin interacting with the Cognite Data Fusion API through our Software Development Kits (SDKs).

You are now ready to use Postman with API keys as authentication method.