AVEVA Data Hub Client Authentication Postman Collection

Version: 1.0.5

Requirements

• Postman version 8.0 or later.
• Register a Client-Credentials Client in your AVEVA Data Hub tenant and create a client secret to use in the configuration of this sample. (Video Walkthrough)
• Access to a Tenant Id
• Optional: access to a Namespace Id and Stream Id

About this sample collection

This sample is meant to be a simple introduction to show how you can use Postman to retrieve a bearer token for authenticating against ADH.

Configuring the sample

Steps:

1. Clone the GitHub repository
2. Open Postman
3. Import the postman_collection.json file to Postman by selecting Collections in the left sidebar and clicking 'Import'. Import the collection as version 2.1 as recommended.
4. Edit the imported collection by clicking its title, then under the 'Variables' tab add your client Id, client secret, and tenant Id to the corresponding variable under the 'Current Value' column.
5. Save the collection using 'ctrl-s' or by clicking the disk icon.
6. Optionally, to test some interactions with the ADH APIs, add a Namespace Id and Stream Id to the corresponding variables. This will let you use the authentication token that we retrieve to make some sample requests to ADH.

Note: Make sure to always save the collection if you make any changes to the variables.

For more information on collection variables, see the Postman docs

AVEVA Data Hub is secured by obtaining tokens from its token endpoint. Client credential clients provide an identifier and an associated secret that are authenticated against this endpoint which we can see in the 'Get or Refresh Bearer Token' request.

(This token endpoint is obtained automatically behind the scenes, but if you are interested in how, you can see it being obtained in the 'Pre-request Script' of the 'Get or Refresh Bearer Token' request)

Running the sample

To run this collection complete the following steps

1. Execute the 'Get or Refresh Bearer Token' request to retrieve an authorization token.
2. See the token returned in the response under the 'access_token' key. This value can now be used to authenticate your requests. A collection variable called 'token' containing this value has also been created.

To use the token in your requests, either copy the value and paste it as the 'Token' under the 'Auth' section of the request, using the 'Bearer Token' authentication type, or simply use the 'token' variable created for you. Take a look at the 'Get Namespaces' request for example.

We have created this variable by adding a Javascript test under the 'Tests' section of the 'Get or Refresh Bearer Token' request that will store the token value every time you execute the request. This is to make refreshing the token simpler, but if desired you can also copy-paste the 'access_token' value from the 'Get or Refresh Bearer Token' response to use as the 'Token' for your requests.

Refreshing the Token

The token has an expiration time after which it expires that is returned under the 'expires_in' key in the response. You should see this set to 3600 in the response, meaning 3600 seconds (1 hour). This expiration time is configurable by editing your client credentials client in the portal.

Once the token has expired, execute the 'Get or Refresh Bearer Token' request to see the new value reflected in the 'token' variable or to copy the new 'access_token' to use in your requests.

Get Tenant Info

The 'Get Tenant Info' request will use your tenant Id and the token to call the ADH Tenant API, returning the basic information for your tenant. Execute the request to see the result.

Sample ADH requests

If you entered namespace and stream identifiers mentioned in the 'Configuring the Sample' section above, execute the remaining 'Get Namespaces', 'Get Streams', and 'Get Data for Stream' requests to see some ADH API use cases.

Note: To make the 'Get Data for Stream' request you will need to replace the placeholders for start index and count under the Params columns. It is also required that the client you are using has the required permissions to read data for the stream, for more information see the video walkthrough of creating a client (Video Walkthrough).

Testing the sample

To test this sample run

npm ci

to install dependencies, then run

npm install -g newman

to install newman

Then replace the placeholders in appsettings.placeholder.json with your values and rename the file to appsettings.json. (The file name appsettings.json is ignored by Git to avoid users accidentally exposing sensitive data)

Then run

newman run ./postman_collection.json -d ./appsettings.json

---

Tested against Postman v9.9.3 For the main ADH Authentication samples page ReadMe
For the main ADH samples page ReadMe
For the main AVEVA samples page ReadMe