Workiva User Management API Guide

Auth method: OAuth 2.0 (client credentials and authorization code flows)

Setup steps

1. Log in to Workiva and navigate to the Developer Portal (developers.workiva.com).
2. Create an API client application to obtain a client_id and client_secret.
3. Request an access token via POST to https://api.app.wdesk.com/iam/v1/oauth2/token using client_credentials grant.
4. Include the returned Bearer token in the Authorization header for all API requests.
5. Ensure the client application has been granted the required scopes by a workspace administrator.

Required scopes

List Users

• Method: GET
• URL: https://api.app.wdesk.com/platform/v1/users
• Watch out for: Pagination uses nextPageToken; iterate until token is absent or empty.

Request example

GET /platform/v1/users?pageSize=50
Authorization: Bearer {token}

Response example

{
  "data": [{"id":"usr_abc","email":"jane@example.com","firstName":"Jane","active":true}],
  "nextPageToken": "tok_xyz"
}

Get User

• Method: GET
• URL: https://api.app.wdesk.com/platform/v1/users/{userId}
• Watch out for: Returns 404 if user does not exist in the authenticated workspace.

Request example

GET /platform/v1/users/usr_abc
Authorization: Bearer {token}

Response example

{
  "id": "usr_abc",
  "email": "jane@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "active": true
}

Create User

• Method: POST
• URL: https://api.app.wdesk.com/platform/v1/users
• Watch out for: Email must be unique; duplicate email returns 409 Conflict.

Request example

POST /platform/v1/users
Authorization: Bearer {token}
Content-Type: application/json

{"email":"new@example.com","firstName":"New","lastName":"User"}

Response example

{
  "id": "usr_new1",
  "email": "new@example.com",
  "active": true,
  "createdAt": "2024-01-15T10:00:00Z"
}

Update User

• Method: PATCH
• URL: https://api.app.wdesk.com/platform/v1/users/{userId}
• Watch out for: Partial updates only; omitted fields are unchanged.

Request example

PATCH /platform/v1/users/usr_abc
Authorization: Bearer {token}
Content-Type: application/json

{"active":false}

Response example

{
  "id": "usr_abc",
  "active": false,
  "updatedAt": "2024-06-01T12:00:00Z"
}

Delete User

• Method: DELETE
• URL: https://api.app.wdesk.com/platform/v1/users/{userId}
• Watch out for: Deletion is permanent. Consider setting active=false for reversible deprovisioning.

Request example

DELETE /platform/v1/users/usr_abc
Authorization: Bearer {token}

Response example

HTTP 204 No Content

List Groups

• Method: GET
• URL: https://api.app.wdesk.com/platform/v1/groups
• Watch out for: Group membership details require a separate GET /groups/{id}/members call.

Request example

GET /platform/v1/groups
Authorization: Bearer {token}

Response example

{
  "data": [{"id":"grp_1","name":"Finance Team","memberCount":12}],
  "nextPageToken": null
}

Add User to Group

• Method: POST
• URL: https://api.app.wdesk.com/platform/v1/groups/{groupId}/members
• Watch out for: User must already exist in the workspace before being added to a group.

Request example

POST /platform/v1/groups/grp_1/members
Authorization: Bearer {token}
Content-Type: application/json

{"userId":"usr_abc"}

Response example

HTTP 201 Created
{"groupId":"grp_1","userId":"usr_abc"}

Remove User from Group

• Method: DELETE
• URL: https://api.app.wdesk.com/platform/v1/groups/{groupId}/members/{userId}
• Watch out for: Does not deactivate the user; only removes group membership.

Request example

DELETE /platform/v1/groups/grp_1/members/usr_abc
Authorization: Bearer {token}

Response example

HTTP 204 No Content

• Rate limits: Workiva's public documentation does not explicitly publish specific rate-limit thresholds or tier-based limits for the Platform API.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No explicit rate-limit values, headers, or Retry-After behavior documented in official sources as of research date. Contact Workiva support for current limits.

• Pagination method: token

• Default page size: 100

• Max page size: 100

• Pagination pointer: pageToken

• Webhooks available: No

• Webhook notes: Workiva's public Platform API documentation does not describe a webhook or event-subscription system for user lifecycle events as of the research date.

• Alternative event strategy: Poll GET /users with updatedAt filtering or use SCIM provisioning via an IdP for event-driven user lifecycle management.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.app.wdesk.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Requires Enterprise plan; not available on lower tiers.
• SCIM token is generated within Workiva admin settings and is workspace-scoped.
• IdP-side connector configuration (e.g., Okta, Azure AD) must use the Workiva-provided SCIM base URL and bearer token.
• SCIM provisioning does not automatically grant document-level permissions; workspace role assignment is separate.
• Workiva does not publish a native Okta or Entra SCIM app in their gallery; configuration is done via generic SCIM 2.0 connector in the IdP.

Provisioning a new employee requires: (1) obtain a Bearer token via POST /iam/v1/oauth2/token;

(2) POST /platform/v1/users with email, firstName, lastName;

(3) capture the returned user id;

(4) POST /platform/v1/groups/{groupId}/members to assign group membership.

Check for an existing user via GET /users?email= before creation-duplicate email returns 409 Conflict.

For deprovisioning, PATCH /platform/v1/users/{userId} with {"active": false} is the preferred reversible action;

DELETE is permanent and cannot be undone via API, so reserve it for post-retention-review cleanup only.

For Enterprise accounts, SCIM 2.0 is available at https://api.app.wdesk.com/scim/v2 using a static bearer token generated in the Workiva admin UI-this token is separate from OAuth 2.0 credentials and is workspace-scoped.

Workiva does not publish a pre-built IdP gallery app;

configure SCIM via a generic SCIM 2.0 connector in Okta or Azure AD.

Note that SCIM group push does not automatically grant document-level permissions inside Workiva;

workspace role assignment remains a separate step.

Provision a new employee via REST API

1. Obtain OAuth 2.0 access token via POST to /iam/v1/oauth2/token with client_credentials grant.
2. POST /platform/v1/users with email, firstName, lastName to create the user account.
3. Capture the returned user id.
4. POST /platform/v1/groups/{groupId}/members with the new userId to assign group membership.
5. Optionally PATCH /platform/v1/users/{userId} to assign workspace roles.

Watch out for: If the email already exists in the workspace, POST /users returns 409; check for existing users with GET /users?email= before creating.

Deprovision a departing employee

1. GET /platform/v1/users?email={email} to resolve the user's id.
2. PATCH /platform/v1/users/{userId} with {"active": false} to immediately disable access.
3. Optionally DELETE /platform/v1/users/{userId} for permanent removal after data retention review.

Watch out for: Deactivation (active=false) is preferred over deletion to preserve audit trails; deletion is irreversible.

Set up SCIM auto-provisioning via IdP (Enterprise)

1. Confirm workspace is on the Enterprise plan.
2. In Workiva Admin, navigate to Security > SCIM Provisioning and generate a SCIM bearer token.
3. Note the SCIM base URL: https://api.app.wdesk.com/scim/v2.
4. In your IdP (e.g., Okta or Azure AD), configure a generic SCIM 2.0 application using the Workiva SCIM base URL and bearer token.
5. Map IdP user attributes to SCIM attributes (userName → email, name.givenName → firstName, etc.).
6. Enable provisioning features: Create Users, Update User Attributes, Deactivate Users.
7. Test with a pilot user before enabling for all users.

Watch out for: Workiva does not have a pre-built IdP gallery app; use the generic SCIM 2.0 connector. Group push via SCIM does not automatically grant document permissions inside Workiva.

The most consequential caveat is the irreversibility of DELETE /platform/v1/users/{userId}-any automation that calls DELETE rather than PATCH active=false will permanently remove user records with no API-level recovery path. OAuth 2.0 tokens are short-lived; omitting token refresh logic will cause silent failures in long-running provisioning jobs.

The SCIM bearer token and OAuth 2.0 tokens are entirely separate credentials with different generation paths and rotation requirements-conflating them in a single secrets store without clear labeling is a common integration error. Role identifiers in the roles array are workspace-specific strings;

always retrieve valid role IDs via GET /roles before assignment rather than hardcoding values. Webhooks for user lifecycle events are not available in the public Platform API; event-driven workflows must fall back to polling GET /users with updatedAt filtering or rely on IdP-side SCIM push as the trigger mechanism.