When generating an API Grant, it's important to keep in mind several leading practices. In this post, we'll be discussing the use of Integration Users, which is a highly recommended practice.

API Grants are used with the Workiva Connector, Workiva Chain Connector, Workiva Scripting Connector, or for authentication with the Workiva APIs. When creating an API Grant, it's necessary to associate a Workiva Username with it. You can find the Workiva Username field highlighted in the green box in the screenshot below.

When choosing a Workiva Username, any user in the selected Workspace can be used. However, it's crucial to consider several factors when making this decision. Although it may seem logical to select the user's account who will use the API Grant to build a Chain or access the Workiva APIs, it's not recommended. In the next paragraphs, we'll explain why and provide some leading practices to follow.

The API Grant will inherit the chosen user's permissions. This includes any Organization roles, Workspace roles, Groups, and individual Workiva object (document, spreadsheet, etc.) permissions assigned to the user. For instance, if the user can edit or delete a specific Spreadsheet, the API Grant will have the same permissions. However, the API Grant's access is limited to the assigned Scopes. This means that even if the selected user has certain permissions, the API Grant may not have the same level of access if the necessary Scopes are not assigned. While not delving too much into Scopes in this post, it's crucial to consider the Scopes assigned to the API Grant to ensure it has the necessary permissions to perform the required tasks while maintaining the appropriate level of security.

It’s important to note that the API Grant's actions will appear as if they were performed by the selected Workiva user in the activities log. This can make it challenging to differentiate between user and API activities. A clear and easy-to-understand activities log that distinguishes between the two is crucial for identifying and resolving issues and providing a comprehensive audit trail. By maintaining a clear record of all activities, it's easier to track the API Grant's usage and ensure compliance with your organization’s policies and procedures.

Also consider the long-term stability of the API Grant when selecting a user associated with a specific person. If the selected user changes roles within the organization or leaves the organization, their account may have a different level of permissions or be deleted altogether. This can result in any Chains or integrations that use the API Grant to break.

Avoid using a specific person's account as the Workiva Username for your API Grant due to the risks outlined above. Instead, create an Integration User, a regular Workiva account for this purpose. An Organization User Administrator adds the Integration User to the organization, and a Workspace Owner or Organization Workspace Administrator adds it to the Workspace. See the screenshot below for an example.

Once the Integration User has been created and added to the Workspace, it can be selected as the value for the API Grant's Workiva Username. By using an Integration User, many of the risks associated with using a specific person's account as the Workiva Username are eliminated.

To further enhance security and control, assign Roles, Groups, and permissions to the Integration User account in a limited fashion. This ensures that the API Grant only has access to the specific areas within Workiva that it needs to interact with, providing greater fine-tuning and security control. All API Grant activities will be logged as the Integration User, ensuring a clear audit trail. Since the Integration User is not tied to a specific person, the API Grant has long-term stability.

To strengthen security and control measures, create a unique Integration User account in Workiva for each integration. Each Integration User can be granted only the minimum required permissions for the specific integration, rather than granting all integration’s required permissions to a single Integration User. Using a single Integration User account and editing or deleting it could break multiple integrations. By using multiple Integration User accounts, these risks are significantly reduced. This approach also provides greater flexibility and control over each integration, allowing for easier troubleshooting and more fine-tuning of permissions and access. This can help ensure each integration functions as intended and any issues can be quickly identified and resolved more easily.

Selecting the appropriate Workiva Username for your API Grant is a critical decision that requires careful consideration. By using an Integration User, you can minimize the risks associated with using a specific person's account, while also providing greater flexibility and control over the API Grant's permissions and access. Creating a unique Integration User account for each integration can further enhance security and control, while also making it easier to troubleshoot any issues that may arise. By following these leading practices, you can help to ensure that your API Grants are stable, secure, and functioning as intended, while also maintaining a clear audit trail of all activities performed using the API Grant.