Postman Configuration For DataTrails

One of my favourite tools for playing with REST APIs 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 provenance and audit trails.

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 for you, along with some example requests.

Of course we’re very pleased with our Python SDK, Jupyter Notebooks, and our OpenAPI Developer Console (requires login) too so if they’re more your speed, go check those out.

Getting Authorized

In order to fully interact with the platform you’re going to need to configure an API credential. DataTrails uses OIDC Client Credentials Flow for this, so you’ll need to create a client ID and secret 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 a credential 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 🙂

Go to your account in DataTrails and select the “Integrations” tab under “Settings”.
Click “+ Custom” and enter a name when prompted. Don’t worry about any other options for now.
Copy the client ID and put it somewhere safe.
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 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_BEARER_TOKEN", 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 😉