Workiva Support Center

Looking to connect to a third party application beyond Workiva's prebuilt Premium Connectors? You can achieve this by leveraging the HTTP Request Connector Commands to interact with REST APIs. 

In this Connected Learning Path, we will create a Chain that authenticates with a third-party API to obtain a bearer token.  While we'll demonstrate this using the Workiva API, the principles and process can be applied to connect with various other APIs.

Step 1: Create Workspace Variables

In order to use Workiva API details across multiple Chains and Commands, we will create Workspace Variables to store that information. We will create three Workspace Variables for the following data: API  Grant Client ID and Client Secret, and IAM (identity and access management) Base URL.

1. From Chain Builder, navigate to Workspace Settings.
2. In Workspace Variables, click the plus sign (+) three times to create three Workspace Variables and configure them as follows:
   • Variable 1:
     • Name: wsv-Workiva API Client ID
     • Value: Input the Client ID of your API Grant.
       To find the Client ID, navigate to your Profile within the Workiva Platform and locate the API Grant under the Security Tab.
       Follow these instructions for more assistance with API Grants.
   • Variable 2:
     • Name: wsv-Workiva API Client Secret
     • Value: Input the Client ID of your API Grant.
       To find the Client Secret, navigate to your Profile within the Workiva Platform and locate the API Grant under the Security Tab.
       Follow these instructions for more assistance with finding your Client Secret

     • Click the lock button in order to encrypt your Client Secret.

       It's important to keep Client Secrets secure; save the Client Secret in a safe location in case you need access to it again.

   • Variable 3:

     • Name: wsv-BaseURL-IAM
     • Value: Enter the value below based on your region. You can verify the region by checking the URL. If the URL contains EU or APAC, use the corresponding URL.

     Note: The US region contains "app" only.

     • US Region
     • EU Region
     • APAC Region

     Field	US Value
     IAM Base URL	https://api.app.wdesk.com

     Field	EU Value
     IAM Base URL	https://api.eu.wdesk.com

     Field	APAC Value
     IAM Base URL	https://api.apac.wdesk.com

   • Save the Workspace Settings.

Step 2: Create a Chain

To generate the Bearer Token, we will create a new Chain with a POST Command; this will give us the Bearer Token we need.

1. Navigate to the Chains Tab within Chain Builder.
2. Create a new Chain, and name the Chain: CLP | Generate Access Token.
3. Include a Description: This chain generates a new Workiva API Access Token.  You must provide a valid Client ID & Client Secret from a previously generated API Grant in the variable values below.
4. Save the Chain.

Step 3: Retrieve a Token

This Chain uses a POST Command from the HTTP Request Connector in order to retrieve our Bearer Token. A Bearer Token is a crucial authentication credential required for accessing APIs. Once obtained within the Chain, the token can be used within subsequent Commands to provide authorization to interact with the API.

1. Add a Post Command from the HTTP Request Connector to the Start area.
2. Double-click the Command to configure it.
   • Rename the Command: POST - Retrieve a Token.
   • Check the Show response checkbox.
   • Populate the URL field with the URL for the endpoint you need to hit. To retrieve a token for the Workiva API, populate the URL with the below, using the Workspace Variable to populate the IAM Base URL.
     1. Click in URL and then click Workspace in the "Select a variable" panel, and select the variable you created in Step 1 (wsv-BaseURL-IAM).
     2. Add /oauth2/token after the variable.
   • In the Content Type field, enter: application/x-www-form-urlencoded.

• Use the Plus sign to add a Header field.
  • Key: Accept
  • Value: application/json

• Use the Plus sign to add another Header field.
  • Key: X-Version
  • Value: 2026-01-01

We will tell the endpoint how to execute using Parameters populated into the Post Form. To do that, click the green plus button next to the Form section 4 times and populate each field with the values below, paying special attention to letter case.

• Field 1:
  • Name: client_id
  • Value: <wsv-Workiva API Client ID>
    In the Select a Variable panel, click the down arrow to expand Workspace and select wsv-Workiva API Client ID.
• Field 2:
  • Name: client_secret
  • Value: <wsv-Workiva API Client Secret>
    In the Select a Variable panel, click the down arrow to expand Workspace and select wsv-Workiva API Client Secret.
• Field 3:
  • Name: grant_type
  • Value: client_credentials
• Field 4:
  • Name: scope
  • Value: Optionally add a value here to specify which scopes this token should have access to.

• Populate the Response with the sample payload below, by doing this, we are providing a format to the Command output, making each variable returned easier to use.

  {
    "access_token": "string",
    "expires_in": "integer",
    "scope": "string",
    "token_type": "string"
  }

3. (Optional) Enter a Description: "This HTTP Command executes a POST call to generate an access token needed for authentication in subsequent HTTP Commands using the Workiva IAM API. This Command leverages Workspace Variables to store the base URL for the Workiva IAM API and the API Grant Client ID and Client Secret. More information can be found here: https://developers.workiva.com/2026-01-01/tokenrequest.html".
4. Save the Command.

Tip! To determine how to populate the Form and Response fields, check out the developer documentation for the API endpoint you're connecting to. For the Workiva API, you can find the Bearer Token documentation here.

Step 4: Test the Exercise

Now that the Chain is complete, test the result.

1. Publish the Chain.
2. Click Execute and then Run Chain.

3. Once the Chain completes its run, you should see that the access token has been generated within the Outputs tab - Response Body of the Post Command.

   

Check out the next exercise within the HTTP Request Connected Learning Path to learn how to use the Bearer Token within a subsequent Command List Spreadsheets.