User Permissions In Power-Ups

We've put together this guide to help you build a Power-Up that correctly manages all of the viewing and writing permissions that exist on the Trello platform.

For more information on how permissions work across workspace types, follow this guide.

Overview

When building a Power-Up, you should keep in mind that Trello boards have a number of visibility options that let board admins control who can see and edit the board. Additionally, when users are members on the board, they are given different write permissions than users who are not members of the boards. Your Power-Up should take these various scenarios into consideration and handle each appropriately.

We've included a number of methods in the Power-Up client library to make it easier for you to handle the various scenarios that arise.

Public Boards

Let's begin with public boards. Public boards are accessible to anyone, regardless of whether they are a logged in Trello user or not. You can detect whether a user is logged in or not using t.isMemberSignedIn; this will synchronously return true or false regarding whether the Trello member is currently signed in.

Some Power-Ups will still want to show information to users who are not logged in viewing public boards. For instance, a Github Power-Up could still show Issue titles and Merge Request information for open source projects (because they are also publicly accessible).

Non-Members On Boards

Next, we can have a user who is logged in, can see a board, but can not write to a board because they are not a member of the board. This can be a public board, or a Workspace board that belongs to a Workspace to which the logged-in member is on.

You can check whether a user can write to a board using t.memberCanWriteToModel. t.memberCanWriteToModelType synchronously returns true or false based on the model type you pass in and the current user's permissions.

Workspace admins of paid Workspaces have board admin permissions on all Workspace boards, including private ones, regardless of whether they are members of the board.

Board Members

You should wrap the parts of your Power-Up that require write permissions with a call to t.memberCanWriteToModel to ensure that a user is never presented with the ability to take an action that they don't have permissions to do.

If a user attempts to take an action for which they don't have the correct permissions via a Power-Up (like a call to t.attach) they will experience an error and be sad users of your Power-Up :frowning:.

Let's dive deeper with an example! Let's assume your Power-Up uses the attachment-sections and card-button capabilities. It uses the attachment-sections to display information about attachments from your service at www.myfriendlyapp.com. When a user attaches a URL from www.myfriendlyapp.com to a card, your Power-Up uses its attachment section to display a bit more information about the link, and displays it to the user. The Power-Up also uses the card button capability to allow users to search through data from your service to add as an attachment.

Because we know that only users with the permission to write on a card can use t.attach we should check in our card-buttons capability whether t.memberCanWriteToModel('card') is true or not before showing them a button to add an attachment!

1
2
TrelloPowerUp.initialize({
  // ...,
  'card-buttons': function(t, options) {
    if(!t.memberCanWriteToModel('card')) {
      // User doesn't have write permissions and so shouldn't
      // be shown any buttons on the card back 🤨
      return [];
    } else {
      // User has write permissions and will be able to use t.attach
      // without any problems 😃
      return [{
        icon: 'https://pathto.com/my/icon',
        text: 'Search My Friendly App!',
        callback: cardButtonCallback
      }];
    }
  }
});

Writing Power-Up Data With t.set()

t.attach isn't the only write operation that the Power-Up library allows users. They can also set Power-Up data using t.set()!

Users that can see a board/card, are logged in, but that cannot write to a board/card are still allowed to set data at a private scope on a board or card via t.set('board', 'private', ...). However, they will not be able to set data at a shared scope.

Edge Case: Private Organizations

Organization admins have the option to set the organization to be private. This means that it can not be viewed unless the logged-in user is a member of the organization. However, organizations can have boards which contain members who are not in the organization.

Non-workspace members on a board will be able to write to both the board and its cards. They will not be able to write to the organization, though. This means that any call you make to t.set('organization', should first check to ensure that t.memberCanWriteToModel('organization') is true.