Workiva Support Center

This guide walks you through importing Workiva API collections into Postman using OpenAPI specifications, configuring environment variables, and validating requests end to end.

Prerequisites

Before you begin, ensure you have the following:

• Postman installed (version 10+ recommended)
• A valid Workiva Client ID and Client Secret
• Access to Workiva OpenAPI .yaml files via the Workiva Developer Portal 
• An understanding of the Workiva environment you are working in: app, eu, or apac

Background

Workiva APIs are published in OpenAPI (.yaml) format. These specifications can be imported directly into Postman, enabling faster development, testing, and integration workflows without manually constructing requests.

Step 1: Import the Workiva API Collection

1. Navigate to the Workiva Platform Code Generation page.
2. Download the OpenAPI .yaml file. 
   
3. Open Postman, select Import, and upload the downloaded file. 
   
4. Confirm that a new collection titled Workiva API appears in Postman. 
   

Step 2: Set Up Your Environment

In Postman, open the Environments tab and create a new environment. For testing purposes, this guide uses an environment named <WorkspaceName>_Workiva_API.

Recommendation: Use a consistent naming convention such as OrganizationName_WorkspaceName to clearly distinguish variables across different Workiva workspaces.

Add the following variables using the Current Value column, then click Save.

📘 How to use environment variables in Postman 

Step 3: Configure OAuth2 – Retrieve a Token

1. Select the Workiva API collection.
2. Set authorization to use the {{access_token}} variable.
3. Select the Scripts tab.

4. Add the following script to the Pre-request section. 

   For 2026 Platform APIs, the X-Version header is required on every request. This script ensures the header is consistently applied across the entire collection, in line with Workiva’s 2026 API versioning requirements.

   Note: This requirement currently applies only to Platform APIs.

   // Add or update X-Version header
   pm.request.headers.upsert({
     key: "X-Version",
     value: pm.environment.get("api_version")
   });

   

    

5. Select the Variables tab.
6. Update the baseUrl variable to use {{environment}} instead of a hardcoded domain.

Original:
https://api.app.wdesk.com/iam/v1

Updated:
https://api.{{environment}}.wdesk.com/iam/v1

Step 4: Save the Access Token

1. From Retrieve a token, select the Scripts tab and add the code below to the Post-request section.

   pm.test("Status code is 200", function () { pm.response.to.have.status(200); }); pm.test("Save access token to environment variable", function () { var jsonData = pm.response.json(); pm.environment.set("access_token", jsonData.access_token); });

   

2. Send the request. You should receive a 200 OK response and your access_token will be saved automatically.

Step 5: Import and Configure the Wdata and Chains API collection

1. Go to the Wdata Code Generation page.
2. Download the .yaml file and import it into Postman (Follow the steps outlined in Step 1: Import the Workiva API Collection).  Note: The .yaml filename will likely be the same as the Workiva API Collection.
3. In the Wdata collection:
   • Set Authorization Type to Bearer Token.

   • Use {{access_token}} as the token value.

     

   • In the Variables tab, update the baseUrl variable to use {{environment}} instead of a hardcoded domain. This makes it easier to switch between environments such as app, eu, or apac.
   • Make sure each request is set to Inherit auth from parent.
   • Repeat the same steps above for the Chains API Collection, ensuring the authorization settings and baseUrl variable are configured in the same way.

Troubleshooting

• Ensure you’re referencing the correct Environment. If the collection defaults to its No environment, switch it to your specified Environment.
• Confirm that the baseUrl variable is consistent across your environment and collection settings.
• Make sure to set the baseUrl collection variable to use {{environment}}; otherwise, your requests may fail.
• If your request returns a 401 or blank response, recheck that your Client ID, Client Secret, API_version and Environment values are correct.