Understanding API Grant Scopes
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).
| Command | Scope(s) |
| Clear Sheet Data | data_tables|w |
| Create New Record Edits | graph:write |
| Create Sheet | data_tables|w |
| Create Spreadsheet | data_tables|w |
| Delete Record | graph:write |
| Delete Sheet | data_tables|w |
| Delete Spreadsheet | data_tables|w |
| Get Record | graph:read |
| Get Records | graph:read |
| Get Reports | graph:read |
| Get Sheet Data | data_tables|r |
| Get Sheet Metadata | data_tables|r |
| Get Spreadsheet Metadata | data_tables|r |
| List Sheets | data_tables|r |
| Overwrite Sheet Data | data_tables|w |
| Publish Spreadsheet | data_tables|r, data_tables|w |
| Retrieve a List of Records | graph:read |
| Retrieve a List of Types | graph:read |
| Retrieve a Single Record | graph:read |
| Retrieve a Single Type | graph:read |
| Run Report | graph:read |
| Update Sheet Metadata | data_tables|w |
| Update Spreadsheet Metadata | data_tables|w |
| Write Sheet Data | data_tables|w |
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.
-
Is there anything about chains/data prep-related scopes that can be added to the table in this article?
For context - we'd like to use this connector to pull listings of all chains, execute & stop chains, pull workspace, environment, chain & underlying command details & run history; and upload and publish mapping groups in Data Prep. etc. -- but are unsure what scopes should be used for the ISU without extensive trial/error testing.
0
Hi Liz Clegg,
Currently, no specific Scope is required to execute a Chains or Data Prep related API endpoint. However, the Workiva Username selected for the API Grant must have permissions to execute the commands you intend to build into your Chain. If you have not already, I recommend reviewing the Integration User Leading Practices for API Grants Start Here post for more information on leading practices around the Workiva Username field.
0Please sign in to leave a comment.
Comments
2 comments