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
Org Security Administrator, sign into Workiva.
- Click your name in the bottom left to open the menu. Select
Organization Adminfrom the menu.
Securityfrom the left menu, select the
Provisioningtab, and click on the
Add Identity or Apibutton.
- From the
Create Identity Provider or API Grantdrop down, select
Client Name, enter a name that will help you identify this grant.
Workspace, enter the workspace that this grant will be attributed to.
Workiva Username, enter the username of the user who needs the grant for the API.
Expires, set when the grant should expire, based on your organization's security policies and preferences.
Scopes, specify the action(s) the system can take on behalf of the user. For example, with the Spreadsheets API, add
Spreadsheets (Write)so the user can access and edit spreadsheets.
- If necessary, enter a comma-separated list of
IP Restrictionsfor the grant.
Add Grantto finish.
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.
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.