t.authorize(url, opts)

Sometimes, such as to complete an oauth flow, you need to show a page in its own new window. For authentication, this is usually because oauth pages (for security reasons) cannot be displayed inside of iframes.

Options

When calling t.authorize you must provide the URL to kick-off the authorization flow and, optionally, include an object containing a set of options. Below are valid values for the option object.

Name	Description
height integer	Height of the window to be opened in pixels.
width integer	Width of the window to be opened in pixels.
validToken function	A function that returns a boolean value to indicate whether the token being returned is valid or not. If the function returns `true`, the Promise started by `t.authorize` will be resolved. If the function returns `false`, the Promise will not be resolved.
windowCallback function	This callback gets called with the handle to the authorization window. This can be useful if you can't call window.close() in your new window (such as the case when your authorization page is rendered inside an iframe).

t.authorize can help you complete these flows. The first argument should be the URL that will be opened in a new window, and the options allow you to specify the size of the window, as well as a validation function if you want to check the token that comes back.

Here is an example of completing Trello's oauth flow using t.authorize:

The name and author parameters are 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 viewing your personal key. If you are using your personal key in your Power-Up, that is considered a legacy app key, and you will need to pass these two parameters to the t.authorize method. Otherwise, Trello has no way of knowing it is tied to your Power-Up.

If your app key is NOT tied to your Power-Up, the provided name and author parameters will be shown to the member when they try to authorize your app. Otherwise, the Power-Up name and author (configured when the Power-Up was created) will be shown.

1
2
const t = window.TrelloPowerUp.iframe();

// When constructing the URL, remember that you'll need to encode your
// APPNAME and RETURNURL
// You can do that with the encodeURIComponent(string) function
// encodeURIComponent('Hello World') -> "Hello%20World"
const oauthUrl =
  "https://trello.com/1/authorize?expiration=never" +
  "&name=[APPNAME]&author=[APPAUTHOR]&scope=read&key=[APIKEY]&callback_method=fragment" +
  "&return_url=[RETURNURL]";

const authBtn = document.getElementById("authorize");
authBtn.addEventListener("click", function () {
  t.authorize(oauthUrl, authorizeOpts)
    .then(function (token) {
      return t
        .set("organization", "private", "token", token)
        .catch(t.NotHandled, function () {
          // fall back to storing at board level
          return t.set("board", "private", "token", token);
        });
    })
    .then(function () {
      // now that the token is stored, we can close this popup
      // you might alternatively choose to open a new popup
      return t.closePopup();
    });
});

t.authorize will return a Promise that you can wait to resolve or reject. The Promise will resolve when either the window.authorize(token) function is called, or an item is stored in localStorage on the same domain under the key 'token'.

The authorize handler opens a new window. Once the auth flow is complete in that window, you should land on a page you control (generally your return_url). That page needs to contain a small amount of javascript to send the resulting token back to the Power-Up.

Here is an example of how that would be achieved for the Trello OAuth flow from above:

1
2
let authorize;

try {
  if (window.opener && typeof window.opener.authorize === "function") {
    authorize = window.opener.authorize;
  }
} catch (e) {
  // Security settings are preventing this, fall back to local storage.
}

if (authorize) {
  authorize(token);
} else {
  localStorage.setItem("token", token);
}

setTimeout(function () {
  window.close();
}, 1000);

Checkout our this Power-Up example Glitch project to see a practical example of how to use t.authorize.