Ctrl+K

Introduction to Permissions Endpoints

Introduction to Permissions Endpoints#

The Permissions endpoints enable access to fetch and modify Permissions for multiple resources within the Workiva Platform. This guide walks you through these questions:

  • How do I fetch Permissions for a resource?

  • How do I fetch the Permissions that can be set?

  • How do I get more information about the Users and Groups that have Permission?

  • How do I modify the Permissions assigned to a resource?

  • How can I filter the assigned Permissions response?

Before getting started, make sure you have credentials set up.

Fetching assigned Permissions for a Document#

To start, let’s fetch the Permissions for a Document. You can find the documentation here. If you’d like to use another resource, you can find a corresponding Permissions endpoint in its endpoint group. For example, look in Spreadsheets for Spreadsheet and Sheet Permissions. Additionally, you can use the Files endpoint to assign Permissions for all top-level resources such as Documents, Spreadsheets, Presentations, Scripts, and Folders.

To retrieve the assigned Permissions for your Document, use this curl command: curl -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/${documentID}/permissions

This response will give you a list of objects that look like this:

{
  "permission": "85aa87ee-beb9-4417-8fa0-420e9de63534",
  "resource": "014b90fd-0631-422c-b94e-1240c53f1d6d",
  "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5MiE",
  "principalType": "user"
}

Let’s break down each of these fields:

  • permission: the ID of the assigned Permission

  • resource: the ID of the resource (Document ID in this case)

  • principal: the ID of the User or Group with this permission

  • principalType: a string communicating if the principal field is a User or Group

We’ll dive into how to resolve each of these IDs, but for now let’s focus on the Permission ID.

Fetch available permissions#

The Permissions API enables a way to query for the available Permissions. You can find that endpoint here. The standard Permissions are:

  • Owner

  • Editor

  • Viewer

  • None

You can retrieve the list of Permissions with this curl command: curl -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/permissions

The ID for each Permission in the list is stable and will not change so you can make this request whenever you need these IDs or save them in your application. By comparing the permission in the Document Permissions and Available Permissions responses, we can see that 85aa87ee-beb9-4417-8fa0-420e9de63534 corresponds to “Editor”. Next, let’s look at getting more information about Users and Groups.

Resolve Principals#

You can assign Permissions to a User or Group and there are different endpoints for each. If your principalType is “user”, use our Get User By ID endpoint here. That curl command would look like: curl -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/admin/organizations/${organizationID}/users/${userID}

If your principalType is “group”, use our Get Group By ID endpoint. That curl command would look like: curl -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/admin/organizations/${organizationID}/workspaces/${workspaceID}/groups/${groupID}

Modify a Document’s Permissions#

Here’s the endpoint to modify a Document’s Assigned Permissions. This endpoint enables you to make multiple assignments and revocations in a single request. To modify an existing permission, it must first be explicitly revoked. Then, the new permission needs to be assigned. To do this in a single request, include that principal in toRevoke as well as toAssign. For example, update a User’s Permission from Editor to Owner by using a curl command like this:

curl -X POST -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/{documentId}/permissions/modification' $'
{
  "toAssign": [
    {
      "permission": "598e8fa3-3e7c-4fb7-b662-f44522216e2b",
      "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5MiE"
    }
  ],
  "toRevoke": [
    {
      "permission": "85aa87ee-beb9-4417-8fa0-420e9de63534",
      "principal": "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5MiE"
    }
  ]
}'

If easier, you can use a programming language like Python to construct the body payload. For example:

import json
import requests
import sys

# Define known IDs
editor_permission = "85aa87ee-beb9-4417-8fa0-420e9de63534"
owner_permission = "598e8fa3-3e7c-4fb7-b662-f44522216e2b"
user_id = "V0ZVc2VyHzU2NDg2NjU2MjQ0NDQ5MiE"
document_id = "a049493019e946479dd80fa4d6771e7b"

# Create ResourcePermissionModification to revoke editor and assign owner
resource_permission_modification = {
  "toAssign": [{
    "permission": owner_permission,
    "principal": user_id,
  }],
  "toRevoke": [{
    "permission": editor_permission,
    "principal": user_id,
  }],
}

# Perform request
access_token = "<token retrieve with https://api.app.wdesk.com/iam/v1/oauth2/token endpoint>"
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': f'Bearer {access_token}'
}

r = requests.post(f'https://api.app.wdesk.com/prototype/platform/documents/{document_id}/permissions/modification', json=resource_permission_modification, headers=headers)

if r.status_code != 204:
    print(f'Failed modification request. Code: {r.status_code} Response: {r.json()} RequestID: {r.headers["x-request-id"]}')
    sys.exit(1)

print("Successfully sent modification")

# Build filter parameters
filter_parameters = {"$filter": f"principal eq '{user_id}'"}
r = requests.get(f'https://api.app.wdesk.com/prototype/platform/documents/{document_id}/permissions', headers=headers, params=filter_parameters)

if r.status_code != 200:
    print(f'Failed to retrieve permissions. Code: {r.status_code}  Response: {r.json()} RequestID: {r.headers["x-request-id"]}')
    sys.exit(1)

print(json.dumps(r.json(), indent=2))

This should cover everything you’ll need to get started. Next, let’s cover some of the filter options that can help you find who has access to a resource.

Filter#

Here are a couple of filter examples to query for more specific Permissions.

Find all Owners of a resource with curl:

curl -G -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/${documentID}/permissions --data-urlencode "\$filter=permission eq '598e8fa3-3e7c-4fb7-b662-f44522216e2b'"

Find assigned Permission for a specific Principal with curl:

curl -G -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/${documentID}/permissions --data-urlencode "\$filter=principal eq 'V0ZVc2VyHzU3MDUxOTQwNzEzOTIyNie'"

Find assigned Permission for a set of Principals with curl:

curl -G -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/${documentID}/permissions --data-urlencode "\$filter=principal in ('V0ZVc2VyHzU3MDUxOTQwNzEzOTIyNie', 'V0ZHcm91cB5XRkdyb3VwOjk2YjY1MDllMmRhNDRlYzI5NmEyYWZiODVhMGUyOGZe')"