API Token Refresh Chain Template

Introduction

When using a chain that makes multiple API calls with an expiring authentication token, such as those used by Workiva's APIs, there is a risk the token may expire before all calls are initiated. If this happens, any remaining API calls will fail. Re-authenticating before every API call could prevent this issue, but it would add additional overhead to the chain.

This guide explains how to implement the Refresh OAuth Tokens Dynamically template. The template is intended for chains that use the HTTP Connector to make API calls where the API requires authentication via a token that has an expiration date and time. While it's built for the Workiva API, it can be adapted for other APIs that use similar authentication methods.

The chain includes a mechanism to automatically refresh the token when it's close to expiring. It subtracts 2 minutes (this value can be adjusted) from the existing token's expiration time as a buffer and compares it to the current time. If the current time is later than the adjusted expiration time, the chain triggers the re-authentication process to generate a new token, which is then output by the chain. If the token is still valid, the chain skips re-authentication and simply outputs the existing token.

Note: If no token is passed through to this chain then it will automatically go through the authentication process and generate one, meaning this chain can also be used for our initial (first) authentication request too along with any subsequent ones.

Prerequisites

Chains

The following connectors must be enabled and configured in your workspace:

The template contains the following Workspace variables designed for use with the Workiva API, change and configure as appropriate:

wsv_platform (the app spot your workspace is located, for the US use "app", EU/EMEA use "eu", APAC use "apac")
wsv_Client ID (your API grant's client ID)
wsv_Client Secret (your API grant's secret)

Deploy the Chain

The “Refresh OAuth Tokens Dynamically” Chain Template is located in the Workiva Chains section of the Templates screen.

Here's how to find it:

In Chain Builder, go to the Templates tab
Select Workiva Chains from the menu at the top
Search for Refresh OAuth Tokens Dynamically Chain Template at the top right and open the template
After locating the template, click New Chain to deploy it to your workspace.
Configure the template for your workspace and API.
Remember to publish the chain once it’s configured and if you wish to use it as it is with no modifications being required.

Note: For detailed instructions on creating a chain from a template, see the Create and manage chains article.

Configure the template

This template can be added to an existing chain using the Run Chain command and will work without any additional modifications for the Workiva API. See here for instructions on how to use the “Run Chain” event command.

An example use case for this chain would be within an existing command group which uses iteration. This chain could be run from a “Run Chain” event command with its own branch in the group, setting dynamic chain variables with the chain outputs from this chain.

Within the "Run Chain" command you can use your dynamic chain variable to ensure it's always the latest token that is checked.

You then need to update that same dynamic chain variable with the output from the the "Run Chain" command.

You can then use that same dynamic chain variables in any HTTP request commands you make

Update the buffer time

By default this template adds a 2 minutes buffer time to the existing token's expiration time to avoid any timing issues. You can change this in the "Check if expiry date time is close" conditional command.