Postman Configuration For DataTrails

One of my favorite 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 using the DataTrails Postman collection.

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

Getting Authorized

In order to fully interact with the platform, you’ll 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.

Note: 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 issue GET 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 😉