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 Org Security Administrator, sign into Workiva.
2. Click your name in the bottom left to open the menu. Select Organization Admin from the menu.

3. Select Security from the left menu, select the Provisioning tab, and click on the Add Identity or Api button.

4. From the Create Identity Provider or API Grant drop down, select Api Grant

5. For Client Name, enter a name that will help you identify this grant.
6. For Workspace, enter the workspace that this grant will be attributed to.
7. For Workiva Username, enter the username of the user who needs the grant for the API.
8. For Expires, set when the grant should expire, based on your organization's security policies and preferences.
9. For Scopes, specify the action(s) the system can take on behalf of the user. For example, with the Spreadsheets API, add Spreadsheets (Read) and Spreadsheets (Write) so the user can access and edit spreadsheets.
10. If necessary, enter a comma-separated list of IP Restrictions for the grant.
11. Click Add Grant to finish.

View API grant secret

Only the user can view their grant's secret by going to the Security tab in their user profile, and then clicking the Regenerate option in the Actions dropdown next to the grant. The user can only view the secret once, so they'll need to copy down the secret in a secure place. If they lose the secret, they'll need to regenerate the secret again.

❗️

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.

Manage API grants

You can edit a specific grant's details or delete the grant by clicking the respective action in the Actions dropdown. However, you won't be able to view the user's grant secret for security purposes.