Workiva Support Center

This guide walks you through importing Workiva API collections into Bruno using OpenAPI specifications. You’ll learn how to configure global environment variables, authenticate using OAuth 2.0, and validate API requests end to end.

Prerequisites

1. Download and install Bruno from www.usebruno.com .

Background

Workiva APIs are published in OpenAPI (.yaml) format. These specifications can be imported directly into API clients like Bruno, allowing you to work with fully structured collections without manually building 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 Bruno. In the top-left corner, click the three-dot menu and select Import Collection.

   

4. Select OpenAPI V3 file and choose the downloaded .yaml file.

   

5. When prompted, create or select a local folder where Bruno will store the collection (for example, Bruno Collections).

   

Step 2: Configure the Global Environment

1. In the top-right corner of Bruno, click the Globe icon and select Configure.

   

2. Choose Create Global Environment.
3. Create the following global variables:
   • access_token
   • Environment
   • ClientID
   • ClientSecret
   • api_version

4. Populate values for Environment, ClientID, and ClientSecret. Leave access_token blank and set api_version to 2026-01-01.

   

5. Save the environment.

Step 3: Configure OAuth 2.0 – Retrieve a Token

To reuse authentication across multiple collections, the OAuth access token will be stored as a global environment variable.

1. Select the Workiva API collection.
2. Select the Variables tab.

3. Update the baseUrl variable to use {{environment}} instead of a hardcoded domain.

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

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

4. Set authorization to Bearer Token and use the {{access_token}} variable.
5. Select the Scripts tab.

6. 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 applied consistently across the 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 (Bruno)
   req.setHeader("X-Version", bru.getGlobalEnvVar("api_version"));
   

   

7. In the Workiva API collection, navigate to the oauth2 folder and open Retrieve a token.

8. In the Post Response script section, add the following to save the token globally:

   const body = res.getBody();
   bru.setGlobalEnvVar("access_token", body.access_token);
   

9. Save your changes.

Step 4: Generate a Bearer Token

1. In the OAuth2 request body, set:
   • {{ClientID}}
   • {{ClientSecret}}
2. Send the Retrieve a token request.

3. If successful, the response will include a Bearer token and it will be saved automatically as a global variable.

   

You can now send authenticated requests. If successful, you’ll see your document list returned in the response.

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:
   • Select the Variables tab.

   • Update the baseUrl variable to use {{environment}} instead of a hardcoded domain.

     Original:
     https://h.app.wdesk.com/s/wdata/oc/api

     Updated:
     https://h.{{environment}}.wdesk.com/s/wdata/prep

   • Set authorization to Bearer Token and use the {{access_token}} variable.
   • 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.