Postman Configuration for DataTrails

This article was originally published as a blog post and is reproduced here.

We’re very pleased with our Python SDK, Jupyter Notebooks, and our OpenAPI Developer Console but sometimes we all want a bit more fine control or command chaining than those can offer. One of my favourite tools for such situations is, of course, Postman. It can make interacting with DataTrails super quick and easy, and help you develop custom workflows for storing and validating your digital evidence ledgers.

Here’s a step-by-step guide to getting a robust Postman set-up configured, and if you head over the Postman public collections you’ll find a link to a pre-baked DataTrails Postman collection with this done of you, along with some example requests.

Getting Authorized

In order to fully interact with the platform you’re going to need to configure a API credential. DataTrails uses OIDC Client Credentials Flow for this, so you’ll need to create a client ID and password in the DataTrails web UI before you get started.

NB DataTrails public attestations are browsable by anyone with no authentication, so if you don’t want to create any data of your own you can skip all this and just issue plain requests from Postman.

Configuring an Application Registration for API access

Sorry, but there’s no way around it: you have to use the web UI one time to set this up. But once you’re done it’s API all the way 

1. Go to your account in DataTrails and select the “Integrations” tab under “Settings”.
2. Click “Custom" and enter a name when prompted. Don’t worry about any other options for now.
3. Copy the client ID and put it somewhere safe.
4. Copy the Secret and put it somewhere safe.
   • BE CAREFUL! This is the only chance you’ll get to copy the secret: if you navigate away or refresh the page it will be hidden and you’ll need to regenerate the secret.
   • BE CAREFUL! This combination of Client ID and Secret grants access to your DataTrails tenancy. Store it carefully and be careful what Access Policies you configure for it. (And before the comments come rolling in, the combination above are fake, not real credentials!

Getting your Application Registration into Postman

You’ll need to set the authorization to a Bearer Token

Next set up 2 variables in the collection Variables screen (with the real values of the client_id and secret that you copied earlier):

With those set, copy and paste this code into the Pre-request Script (big thanks to Utkarsha Bakshi for this Medium post):

pm.sendRequest({ 
    url: "https://app.datatrails.ai/archivist/iam/v1/appidp/token",
    method: 'POST',
    header: {
        'Accept': 'application/json',
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: {
        mode: 'urlencoded',
        urlencoded: [
            {key: 'grant_type', value: 'client_credentials'},
            {key: 'client_id', value: pm.variables.get('datatrails_client_id')},
            {key: 'client_secret', value: pm.variables.get('datatrails_client_secret')} 
        ] 
    } 
}, 
    (err, res) => { 
        pm.globals.set("DATATRAILS_BEARERTOKEN", res.json().access_token)
        console.log(res.json()); 
});

Now make sure that your requests use “Inherit Auth From Parent” (should be the default) and every request you make will get a brand new Access Token! No more head scratching on 401s 

Happy POSTing!