API Reference

Setup

To use the Workiva Admin API, your Workiva account's administrator first creates integration users and their authentication grants. If necessary, request administrator access to your account, or work with your account administrator to create the users and grants.

Integration Users

For each integration, create a new unique Workiva user. Any calls using the API are on behalf of these users, and any historical edits show as being made by them. Using new integration users rather than existing users helps limit the data each integration can access and clearly separates edits made by actual users from those made through an integration.

The APIs respect user permissions, so make sure each integration user has appropriate access to the data it needs. For example, to edit documents, the integration user needs to be a Creator and Manager.

OAuth2 Grants

To access the Workiva Admin API, each integration user requires an OAuth2 grant. To create an authentication grant:

  1. As an account administrator, sign into Workiva.
  2. From Home, select Classic Wdesk from your name's menu then select Classic Account Admin.

Account Admin Tab

  1. On the People tab, select the OAuth2 Grants tab, and click Add a grant.
  2. For Grant Name, enter the name of the system to authenticate with.
  3. For Username, enter the username of the integration user to use the grant.
  4. For Scope, specify the action the system can take on behalf of the integration user. For example, to integrate with Spreadsheets, add Spreadsheets (Read) and Spreadsheets (Write) so the user can access and edit spreadsheets.
  5. For Expiration, set when the grant should expire, based on your organization's security policies and preferences.
  6. If necessary, enter a comma-separated list of allowed IP addresses for the grant, and click Create Grant.
  7. From the grant's menu, select Edit, and record its client ID and secret somewhere safe.

❗️

Keep your client ID and secret safe

The client ID and secret can be used to obtain the bearer token allowed to perform API operations on behalf of a user. Store your client ID and secret in a safe location, not committed with source code.