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:
- As an account administrator, sign into Workiva.
- From
Home
, selectClassic Wdesk
from your name's menu then selectClassic Account Admin
.
- On the
People
tab, select theOAuth2 Grants
tab, and clickAdd a grant
. - For
Grant Name
, enter the name of the system to authenticate with. - For
Username
, enter the username of the integration user to use the grant. - 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. - For
Expiration
, set when the grant should expire, based on your organization's security policies and preferences. - If necessary, enter a comma-separated list of allowed IP addresses for the grant, and click
Create Grant
. - 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.