To use the Workiva Platform 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.
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.
To access the Workiva Platform API, each integration user requires an OAuth2 grant. To create an authentication grant:
- As an account administrator, sign into Workiva.
Classic Wdeskfrom your name's menu then select
Classic Account Admin.
- On the
Peopletab, select the
OAuth2 Grantstab, and click
Add a grant.
Grant Name, enter the name of the system to authenticate with.
Username, enter the username of the integration user to use the grant.
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.
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
- 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.