Postman Configuration For RKVST

One of my favourite tools for playing with REST APIs is, of course, Postman. It can make interacting with RKVST super quick and easy, and help you develop custom workflows for storing and validating your digital evidence and provenance.

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 RKVST 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 a API credential. RKVST uses OIDC Client Credentials Flow for this, so you’ll need to create a client ID and password in the RKVST web UI before you get started.

NB RKVST 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 🙂

Go to your account in RKVST and select the “App Registrations” tab under “⚙ Manage RKVST”.
Click “Add App Registration” 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 RKVST 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.rkvst.io/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('rkvst_client_id')},
            {key: 'client_secret', value: pm.variables.get('rkvst_client_secret')}
        ]
    }
},
    (err, res) => {
        pm.globals.set("RKVST_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 😉