Workiva Support Center

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 oas.yaml file.

3. Open Bruno. In the top-left corner, click the + icon and select Import Collection.

   

4. Click the "choose file(s)" link and choose the downloaded .yaml file.

   

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

   Optionally, change your Folder arrangement from "Tags" to "Paths" and click Import.

   

Step 2: Configure the Global Environment

1. In the Workspace section of Bruno, click the Global Environments Tab then click Create Environment.

   

2. Type a name for your Global Environment then click Create.

    

3. Create the following global variables:
   • access_token
   • ClientID
   • ClientSecret
   • api_version

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

   

5. Save the variables.

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 from the Workspace area of Bruno.

   

2. Click the Workiva dropdown in the upper right corner of the Bruno screen and select the appropriate Environment/region from the Collection list.

   

3. Click the "Auth" tab, select "Bearer Token" from the drop-down and Set the "Token" field to use the {{access_token}} variable.

   

4. Select the Script tab.

5. 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. Documentation can be found here: https://developers.workiva.com/2026-01-01/versioning.html

   Note: This requirement currently applies only to Platform APIs.

   // Add or update X-Version header (Bruno)
   req.setHeader("X-Version", bru.getGlobalEnvVar("api_version"));
   

   

   Click the "Save" button at the bottom left of the Workspace area when finished.

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

   

7. Click the ">>" icon under the Url and click on the "Script" tab.

   

   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);
   

8. Save your changes.

Step 3a (Optional): Import Additional Workiva APIs

Follow the same sequence of steps above to import additional Workiva APIs:

wData OpenAPI oas.yaml file can be downloaded from here

Chains OpenAPI oas.yaml file can be downloaded from here

Step 4: Generate a Bearer Token

1. For the OAuth2 request body, set the following variables (if they have not already been set):
   • {{ClientID}}
   • {{ClientSecret}}

     • To set (or check) the variables, click Workiva in the upper-right of the Bruno workspace, click the Global tab and choose "Configure".

       

       Edit the variables, as necessary.

       

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.

Troubleshooting

• Ensure you’re referencing the correct Environment. If the collection defaults to its No environment, switch it to your specified Environment.
• If your request returns a 401 or blank response, recheck that your Client ID, Client Secret, API_version and Environment values are correct.