The Workiva Connector, Workiva Chain Connector, Workiva Scripting Connector, and the Workiva APIs all require an API Grant for authentication. In this post, we’ll delve into the API Grant creation and management form fields and provide important considerations for each.

API Grants can be created and managed in either the Organization Admin or Workspace Settings. Use the following two links for information on both areas.

• Create and manage API grants in Organization Admin
• Create and manage API grants in workspace settings

A distinction between these two locations is that Organization Admin allows you to create and manage API Grants across all Workspaces within the Organization, while Workspace Settings enables you to create and manage API Grants for the specific Workspace. It is important to note that the account roles and permissions differ for accessing Organization Admin compared to Workspace Settings. See Organization Roles and Workspace Roles to learn more. Regardless of the location, you will find an API Grant creation/edit form, which resembles the screenshot below.

Let's examine each field in this form more closely. It's important to note that all fields marked with an asterisk (*) must be filled out in order to create or modify an API Grant. After an API Grant has been created, those with access to Organization Admin/Workspace Settings can modify the values in each field, except for the Workspace field, at any time.

Client Name
The Client Name field does not impact the functionalities of the API Grant. However, it is advisable to assign a descriptive name to the Grant for easy identification in the future, along with its intended purpose. Creating multiple API Grants with distinguishable names can save time and effort. A recommended approach is to use the name of the Workspace and its purpose. For instance, examples like "SEC Filing Workspace | Chains", "GRC Workspace | Graph API Read", and "GRC Workspace | Graph API Write" allow for quick identification of the Workspace they belong to (especially when viewed from Organization Admin) and their specific purpose, such as usage within Chains or performing read or write operations via the Platform Graph API.

Client Type
Currently, the only available client type is "OAuth2 Client Credentials." This client type is mandatory for all API Grants. While Workiva may introduce additional client types in the future, for now, "OAuth2 Client Credentials" is the required option.

Workspace
The Workspace field allows you to select the specific Workspace to which the API Grant will be attributed. It is important to note that API Grants can only interface with the Workspaces they are attributed to. If your workflow involves interacting with multiple Workspaces, you will need to create a separate API Grant for each Workspace. Additionally, if you are creating an API Grant through Workspace Settings, please be aware that you will not have the ability to change the attribution of the Grant to a different Workspace.

Workiva Username
When selecting a Workiva Username, you have the flexibility to choose any user within the selected Workspace. However, it is important to consider certain factors when making this decision. While it may seem logical to choose the account of the user who will utilize the API Grant to build a Chain or access the Workiva APIs, it is not recommended. The leading practice is to use an integration user. For more detailed information, please refer to the Integration User Leading Practices for API Grants Start Here post.

Scopes
API Grants inherit the permissions of the Workiva user selected in the Workiva Username field. However, it is still necessary to assign Scope(s) in order to successfully perform actions. The recommended approach is to assign only the minimum required Scopes to an API Grant, based on the specific tasks it will be used for. For more detailed information, please refer to the Understanding API Grant Scopes Start Here post.

Expires
The Expires field provides the option to specify an expiration date for the API Grant, on which it will no longer be valid. You can choose any future date for expiration. If you leave this field blank, the Grant will remain active indefinitely. It is advisable to consult your company's security policies to determine an appropriate expiration date.

Ip Allowlist
In the Ip Allowlist field, you have the option to define a comma-separated list of allowed IP addresses that can utilize this API Grant. Any requests originating from an IP address not included in the Ip Allowlist will be rejected. If you leave this field blank, no IP address filtering will be applied.