Assign permissions to lots of users with the API

Support Article
, , , ,
1

This post is a wiki post.
All users can edit this post to improve its documentation.

When a project is shared with lots of users, the UI may slow down and/or become unresponsive.

The solution below can be used as a workaround to assign permissions to many users at once.

Requirements:

  • A REST client (e.g.: Postman, Insomnia etc…).
  • To be comfortable with advanced use of an API

First you need to retrieve your API token

With your browser, go to https://kf.kobotoolbox.org/token/ and copy the token you get.
(You can replace kf.kobotoolbox.org by your domain if needed)
You should see something like:

{
    "token": "aa1111111aaaaaaaaaa11aa1a1aaaa"
}

Your token is aa1111111aaaaaaaaaa11aa1a1aaaa

In this example, we are using Insomnia as the RESt client.

Go to Download - Insomnia
Download “Insomnia Core” for your operating system.

When install the software and open it.

  • Create a new request

    1. Click the + symbol
    2. Create new request
    3. Change GET to POST
    4. Change No Body to JSON
    5. Use the name you want
    6. Click create
      image

  • Click on Auth tab

    1. Change the type by clicking on the arrow from No authentication to Bearer Token
    2. In token field: enter the token you got at the beginning
    3. Prefix: Type Token
      image
      image531×613 21.5 KB

      image

  • Change API endpoint

    1. On the textbox on the top, enter the url of the API endpoint used for permissions: https://kf.kobotoolbox.org/api/v2/assets/<asset_uid>/permission-assignments/bulk/
      2.<asset_uid> is the unique string of the project.

  • Build the permissions for API requests
    This part is a little tricky when you are not used to and it could look like more complicated than it is really.
    Let’s assume this:

  • user1 is allowed to see user2 and user3 submissions
  • user2 can only add data
  • user3 can only add data
  • user1, user2, user3 are usernames1. Open JSON tab and copy and paste this json below
[
  {
    "permission": "https://kf.kobotoolbox.org/api/v2/permissions/add_submissions/",
    "user": "https://kf.kobotoolbox.org/api/v2/users/user2/"
  },
  {
    "permission": "https://kf.kobotoolbox.org/api/v2/permissions/add_submissions/",
    "user": "https://kf.kobotoolbox.org/api/v2/users/user3/"
  },
  {
    "partial_permissions": [
      {
        "filters": [
          {"_submitted_by": {"$in": ["user2", "user3"]}}
        ],
        "url": "https://kf.kobotoolbox.org/api/v2/permissions/view_submissions/"
      }
    ],
    "permission": "https://kf.kobotoolbox.org/api/v2/permissions/partial_submissions/",
    "user": "https://kf.kobotoolbox.org/api/v2/users/user1/"
  }
]

2. Click Send.

I hope it helps

3 Likes