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
.yamlfiles via the Workiva Developer Portal - An understanding of the Workiva environment you are working in:
app,eu, orapac
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
- Navigate to the Workiva Platform Code Generation page.
- Download the OpenAPI
.yamlfile. - Open Postman, select Import, and upload the downloaded file.
- 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.
| Variable | Type | Initial Value | Current Value |
|---|---|---|---|
| access_token | default | (leave blank) | (leave blank) |
| environment | default | (leave blank) |
app, eu, or apac
|
| ClientID | default | (leave blank) | Your Client ID |
| ClientSecret | secret | (leave blank) | Your Client Secret |
| api_version | default | (leave blank) |
2026-01-01
|
📘 How to use environment variables in Postman
Step 3: Configure OAuth2 – Retrieve a Token
- Select the Workiva API collection.
- Set authorization to use the
{{access_token}}variable. - Select the Scripts tab.
-
Add the following script to the Pre-request section.
For 2026 Platform APIs, the
X-Versionheader 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") }); - Select the Variables tab.
- Update the
baseUrlvariable 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
-
From Retrieve a token, select the Scripts tab and add the code below to the Post-request section.
-
Send the request. You should receive a 200 OK response and your
access_tokenwill be saved automatically.
Step 5: Import and Configure the Wdata and Chains API collection
- Go to the Wdata Code Generation page.
- Download the
.yamlfile and import it into Postman (Follow the steps outlined in Step 1: Import the Workiva API Collection). Note: The.yamlfilename will likely be the same as the Workiva API Collection. - In the Wdata collection:
- Set Authorization Type to Bearer Token.
-
Use
{{access_token}}as the token value. - In the Variables tab, update the
baseUrlvariable to use{{environment}}instead of a hardcoded domain. This makes it easier to switch between environments such asapp,eu, orapac. - 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
baseUrlvariable 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
baseUrlvariable is consistent across your environment and collection settings. - Make sure to set the
baseUrlcollection 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.