When generating an API Grant, it’s important to keep in mind several leading practices. In this post, we’ll be discussing API Grant Scopes.

API Grants are typically used for creating a Workiva Connector, Workiva Chain Connector, Workiva Scripting Connector, or for authentication with the Workiva APIs. When creating an API Grant, it is necessary to select Scope(s). You can find the Scope field in the API Grant creation form highlighted in the green box in the screenshot below.

API Grants inherit the permissions of the Workiva user chosen in the Workiva Username field. For a review of the Workiva Username field and leading practices around selecting the right user, please see the post Integration User Leading Practices for API Grants.

Although the API Grant inherits permissions from the Workiva user assigned to it, Scope(s) must still be assigned to perform actions successfully. For example, if the Workiva user has permission to edit a Spreadsheet, but the API Grant doesn't have the data_tables|w Scope assigned, any attempt to edit the Spreadsheet using this API Grant will fail. This is because, in addition to the Workiva user's permission to edit the Spreadsheet, the data_tables|w Scope is also required to perform Spreadsheet edit tasks.

The leading practice is to only assign the minimum required Scopes to an API Grant necessary to perform the tasks that it will be used for. In conjunction with selecting the appropriate Workiva user, limiting the Scopes to only the required ones allows you to narrow down the potential access that the API Grant has within the Workiva Platform.

For quick reference, below is a table of commonly used Workiva Connector Commands and their required Scope(s).

If you don't have the right permission to execute a Workiva Command, you'll get a 403 error. For instance, if you try to update Sheet data without the necessary Scope assigned to the API Grant, you'll see this message in the logs of the failed node: "Error updating sheet data: Missing required oauth scopes: data_tables|w. Code 403". This error message is useful because it explains why the command failed and which Scope is missing.

If you would like to look further into the other available Workiva Commands and are willing to browse through API documentation, you can locate the API endpoint documentation of a corresponding Workiva Command to learn which Scope(s), if any, are required. For example, the API endpoint documentation corresponding to the command Get Record is Retrieve a Single Record. In the “Required OAuth Scopes” section, you’ll find that the graph:read Scope is required.

Limiting an API Grant's Scopes to only what's necessary is a leading practice for security reasons. It's also leading practice to create multiple API Grants, each with specific Scopes for different integrations, instead of using a single API Grant with a wide range of Scopes. This way, each API Grant only has access to the data and functionality it needs.