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