Workiva Support Center

This article is for:

• Org Security Admins

Create an API grant

To access any Workiva API’s, users will need an API grant for authorization. As an Org Security Admin, you create an API grant for a user, you’ll be able to edit the grant’s details or delete the grant. However, only the user will be able to view their grant’s secret by regenerating the grant in their user profile.

To begin creating an API grant:

1. In the top right, click the user icon and select Admin from the dropdown.
2. Then select Organization admin from the dropdown.
   
3. On the Organization Admin page, select Security in the left menu pane and then select the Provisioning tab.
   
4. Under Create Identity Provider or API Grant, click Add Identity or API.
   

5. Select API Grant in the dropdown.
   

   The following instructions are for an API Grant. For an Identity Provider, refer to Manage and provision users with SCIM.

6. Enter the following information for the API grant:
   • In Client Name, enter a name that will help you identify this grant.
   • In Workspace, enter the workspace that this grant will be attributed to.

   • In Workiva Username, enter the username of the user who needs the grant for the API.
     Only this user is able to view this API grant’s secret in My profile > Security.

     Note: For security purposes, changing the Workiva Username invalidates the current secret, and only the new username will have access to the new secret.

   • In Scopes, specify the action(s) the system can take on behalf of the user.
     For example, for the Spreadsheets API, add Spreadsheets (Read) and Spreadsheets (Write) so the user can access and edit spreadsheets.
   • In Expires, set when the grant should expire, based on your organization's security policies and preferences.
   • (Optional) Enter a comma-separated list of IP addresses to the IP Allowlist for the grant.
     
7. Click Add Grant to finish.

Manage API grants

You can edit a specific grant’s details or delete a grant by clicking the respective action in the Actions dropdown for that grant.

View API grant secret

To view the API secret, 

1. In the top right, click the user icon and select My profile from the dropdown.
   
2. Click the Security tab.
3. Locate the API Grant that you want the secret for.
4. Click Regenerate in the Actions dropdown next to the grant.

Important Notes

• Only the user who’s specified in the API grant’s details can view their grant’s secret.  
• You can only view the secret once, so you will need to copy down the secret in a secure place.
  If you lose the secret, you will need to regenerate the secret, and then populate all the places that require it with the new secret.
• Tip: The secret begins with "wk_secret:"

What's next? 

• Manage and provision users with SCIM
• Manage activity retention settings
• Create and manage API grants in workspace settings