Setup

The following steps will need to be performed by an account administrator of your Wdesk account. If you’re not an administrator, please contact your account administrator to discuss becoming an administrator, or work with them to complete the process of creating an integration user and authentication grant, as outlined below.

Creating an Integration User

The first thing you’ll want to do is to create a new Wdesk user, or users, that will be used for the integration. In the next section, you’ll create an OAuth2 grant associated with a Wdesk user. Any calls using the API will be done on behalf of that user and any historical edits to a Wdesk document will show as being made by the user that is associated with the OAuth2 grant. APIs will respect user permissions, so you will need to ensure that the provided user has Editor access to the Spreadsheets that you’d like to integrate with.

At this time, we do not provide a separate integration user role, so you’ll need to create a new user and associate that user with the OAuth2 grant. Your integration user will need to be a Creator or Manager in order to make changes to documents. Creating a new user for the integration, instead of using an existing user, will also help limit the documents that the integration has access to and will make a clear separation between edits performed by an actual user and those performed through an integration.

Best Practice: We recommend creating a unique user for each integration. This will help make it more clear which changes that were made by each integration and will allow you to limit the scope of access for each integration to only the documents appropriate for that integration.

Creating an OAuth2 Grant in Wdesk

Now that you have an integration user, we’ll cover everything needed to create the authentication grant needed to access the Wdesk Workiva Developer API.

  • Login into Wdesk as an account administrator and create an OAuth2 grant from the Account Admin People tab.
    • Select "Admin" from Wdesk Home.

      • Select "Account Admin" from the “Admin” menu image alt text
    • Select the "People" tab.

      • Select the "OAuth2 Grants" tab image alt text
    • In the "Add An OAuth2 Grant" menu enter the information below.

      • Grant Name - This is the name of the system that will be authenticated by the grant.
      • Username - This the the username that will be used to authentic the user within Wdesk.
      • Scope - This specifies the action that the system can take on behalf of this user. For example, to integrate with Spreadsheets, add "Spreadsheets (Read) to allow reading of Spreadsheet data and “Spreadsheets (Write)" to allow writing Spreadsheet data.
      • Expiration - This is the date that the grant will expire. This is configurable based on the security policies and preferences of our customers.
  • Once the grant has been created the Wdesk user will click "Edit" from the “OAuth2 Grants” menu, which will open a dialog that includes the following:
    • Client ID - This is a randomly generated ID that will be used to identify users of this grant.
    • Client Secret - This is a randomly generated ID that will be used to authenticate users of this grant.
  • With the "OAuth2 Grants" still open:
    • Copy the Client ID and Client Secret from the "OAuth2 Grants" Edit window and store it somewhere safe.