REST API Client

The REST API client provides methods to make it easier to interact with Trello's REST API from a Power-Up. The client primarily helps with authorization; it makes it easy to get a user's OAuth token when you provide your API key.

To get started, you will need to obtain your Trello API key. You can do so by logging into Trello and visiting the https://trello.com/power-ups/admin page, then access your Power-Up, navigate to the API Key tab and select the option Generate a new API Key. Your API key is unique to your Power-Up and will be used to authorize your API requests along with the user token generated when the user consents access to your Power-Up.

Then, add your API key (appKey), the name of your app (appName), and the name of your company / your name (appAuthor) when you call .initialize() for your Power-Up. The name and author of your app specified here will be shown to the member when they authorize your app only if the app key you're using isn't tied to a Power-Up.

Issues due to Third Party Storage Partitioning on Chrome

client.getToken() and client.isAuthorized() functions may not work correctly on the latest version of Chrome, due to its introduction of "Third Party Storage Partitioning". If you are running into issues getting the REST API client working, you may want to disable this feature.

You can do that by navigating to Chrome's flags settings via chrome://flags/#third-party-storage-partitioning, and setting "Third Party Storage Partitioning" to "disabled".

Client Initialization

Required options

Note that both the appName and appKey options must be included for the API client to be available. If you call getRestApi without including them, it will throw an exception.

The appAuthor option is only required if the app key you're using is not tied to a Power-Up. You can verify this by visiting the app key page and looking for a personal key, if there is one and it the same one you're using in your Power-Up then make sure you're passing this parameter as that is a legacy app key and Trello has no way of knowing it is tied to your Power-Up.

Also note that the appName and appAuthor options you include when setting up your Power-Up is shown to the member when they authorize your app only if the app key you're using is NOT tied to your Power-Up, otherwise the Power-Up name and author will be shown.

On your connector iframe:

1
2
window.TrelloPowerUp.initialize(
  {
    // ...
    // This is where you declare your capabilities
    // ...
  },
  {
    appKey: "my-trello-key",
    appName: "My Power-Up",
    appAuthor: "My Company",
  }
);

You may also use the API client from an iframe by specifying these options when initializing the iframe helper:

1
2
var t = window.TrelloPowerUp.iframe({
  appKey: "my-trello-key",
  appName: "My Power-Up",
  appAuthor: "My Company",
});

Getting API Client Instance

After you've initialized the Power-Up client library with your appKey, appName, and appAuthor (This option may not be required depending on the type of app key you're using, see: Required options) you can call t.getRestApi() to get an instance of the API client.

t.getRestApi() returns a Promise.

For example, on your connector iframe:

1
2
window.TrelloPowerUp.initialize({
  'card-buttons': function(t) {
    return t.getRestApi()
    	// We now have an instance of the API client.
      .isAuthorized()
      .then(function(isAuthorized) {
        if (isAuthorized) {
          return [{
            text: 'David\'s Power-Up',
            callback: showMenu
          }];
        } else {
          return [{
            text: 'David\'s Power-Up',
            callback: showIframe
          }];
        }
      });
}, {
  appKey: 'my-trello-key',
  appName: 'My Power-Up',
  appAuthor: 'My Company'
});

And on a different iframe within the Power-Up:

1
2
<!DOCTYPE html>
<html lang="en">
  <body>
    <script src="https://p.trellocdn.com/power-up.min.js"></script>
    <script>
      var t = window.TrelloPowerUp.iframe({
        appKey: "your-app-key",
        appName: "My Great Power-Up",
        appAuthor: "My Company",
      });
      t.render(function () {
        t.getRestApi()
          .isAuthorized()
          .then(function (isAuthorized) {
            alert("Success!");
          });
      });
    </script>
  </body>
</html>

client.authorize(opts)

Use client.authorize to kick off the auth flow and get a token you can use to make requests to the Trello REST API on behalf of the member. Returns a Promise which will resolve with a token when the auth flow is complete.

Note that the appName and appAuthor params you include when setting up your Power-Up is shown to the member when they authorize your app only if the app key you're using is NOT tied to your Power-Up, otherwise the Power-Up name and author will be shown.

When you use client.authorize, it handles storing the token securely for you. You may call client.isAuthorized or client.getToken to check if you have already been authorized, or to retrieve the token. The token is stored in private plugin data, so the member will only need to auth once.

The authorize function accepts an optional opts object which can have the following optional parameters:

Parameter	Default Value	Notes
expiration	`"never"`	One of: `1hour`, `1day`, `30days`, `never`
scope	`"read"`	Comma separated list of: `read`, `write`, `account`
return_url	the value of `window.location.href`	The URL to redirect to at the end of the auth flow. You generally don't want to change this. We also recommend that you specify the origins that your application will redirect to when completing authorization.

Note that this method kicks off Trello's full consent flow. This flow opens a browser popup that asks the member to sign in if they are not already, and then prompts them to grant your app the requested permissions.

To prevent the browser from blocking Trello's consent popup, only call client.authorize from a click handler on your domain.

The best way to handle this is to use one of the UI helpers or capabilities that lets you specify an iframe URL. These include t.popup, t.modal, and the attachment-section and card-back-section capabilities.

Don't call client.authorize from a capability handler!

You might be tempted to call client.authorize from a capability handler, for example, from a card-buttons callback. Unfortunately this does not register as a click by the browser, and it will block the consent popup. Instead, open a t.popup from your card-button handler, and load an iframe that contains a button that calls client.authorize.

Here is an example of how to correctly call client.authorize in a way that won't trigger the popup blocker. The first part is in your iframe connector:

1
2
function showIframe(t) {
  return t.popup({
    title: "Authorize to continue",
    url: "./authorize.html",
  });
}

function showMenu(t) {
  return t.popup({
    title: "Do something cool",
    items: [
      // …
    ],
  });
}

window.TrelloPowerUp.initialize(
  {
    "card-buttons": function (t) {
      return t
        .getRestApi()
        .isAuthorized()
        .then(function (isAuthorized) {
          if (isAuthorized) {
            return [
              {
                text: "David's Power-Up",
                callback: showMenu,
              },
            ];
          } else {
            return [
              {
                text: "David's Power-Up",
                callback: showIframe,
              },
            ];
          }
        });
    },
  },
  {
    appKey: "your-app-key",
    appName: "My Great Power-Up",
    appAuthor: "My Company",
  }
);

Then, authorize.html should look like this:

1
2
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Authorize</title>
  </head>
  <body>
    <button type="button">Click to authorize</button>
    <script src="https://p.trellocdn.com/power-up.min.js"></script>
    <script>
      var t = window.TrelloPowerUp.iframe({
        appKey: "your-app-key",
        appName: "My Great Power-Up",
        appAuthor: "My Company",
      });
      t.render(function () {
        document.querySelector("button").addEventListener(
          "click",
          function () {
            t.getRestApi()
              .authorize({ scope: "read,write" })
              .then(function (t) {
                alert("Success!");
              });
          },
          false
        );
      });
    </script>
  </body>
</html>

Handling Cancellations

If the member chooses not to authorize your app for whatever reason, t.authorize will reject the promise with TrelloPowerUp.restApiError.AuthDeniedError. Here is an example of how to handle that:

1
2
document.querySelector("button").addEventListener(
  "click",
  function () {
    t.getRestApi()
      .authorize({ scope: "read,write" })
      .then(function (t) {
        alert("Success!");
      })
      .catch(TrelloPowerUp.restApiError.AuthDeniedError, function () {
        alert("Cancelled!");
      });
  },
  false
);

client.getToken()

Returns a promise that resolves to the token obtained from a previous call to client.authorize, if there is one. If the member has not authorized your app yet, resolves to null.

1
2
t.getRestApi()
  .getToken()
  .then(function (token) {
    if (!token) {
      // do auth instead
    }

    // make a request with token
  });

client.isAuthorized()

Returns a promise which resolves to a boolean indicating whether the member has authorized your Power-Up to make API requests on their behalf. You can use this to determine whether you should call t.authorize.

Note also that most capabilities allow you to return a promise from your handler function. You may use this to return a slightly-different UI based on whether the member has authorized you or not.

1
2
window.TrelloPowerUp.initialize(
  {
    "card-buttons": function (t) {
      return t
        .getRestApi()
        .isAuthorized()
        .then(function (authorized) {
          if (authorized) {
            // return signed-in button
          } else {
            // return signed-out button
          }
        });
    },
  },
  {
    appKey: "my-api-key",
    appName: "My Trello App",
    appAuthor: "My Company",
  }
);

client.clearToken()

Returns a promise that removes the stored token when resolved.

1
2
window.TrelloPowerUp.initialize({
  'card-buttons': function(t) {
    return t.getRestApi()
    .clearToken()
    .then(function() {
      // No token is stored currently.
    })
 }, {
  appKey: 'my-api-key',
  appName: 'My Trello App',
  appAuthor: 'My Company'
});

API Client Availability

The API client is only available from the t object you receive in a capability function, or inside an iframe. It is not available from the object returned by window.TrelloPowerUp.initialize.

In other words, these examples work (remember that appKey and appName must be specified, see Required options for more information):

1
2
window.TrelloPowerUp.initialize(
  {
    "card-buttons": function (t) {
      t.getRestApi(); // Works!
    },
  },
  {
    appName: "My Killer App",
    appKey: "my-trello-key",
    appAuthor: "My Company",
  }
);

This works too:

1
2
var t = window.TrelloPowerUp.iframe({
  appName: "My Killer App",
  appKey: "my-trello-key",
  appAuthor: "My Company",
});

t.getRestApi(); // Works!

However, this does not work!:

1
2
var t = window.TrelloPowerUp.initialize(
  {
    // …
  },
  {
    appName: "My Killer App",
    appKey: "my-trello-key",
    appAuthor: "My Company",
  }
);

t.getRestApi(); // Does not work!