OAuth 2.0 Client Configuration

In this document, we'll dive deeper into different concepts regarding an OAuth 2.0 client's configuration. You can manage your OAuth 2.0 client by finding your app in the Trello apps administration page, and clicking on the "OAuth 2.0" tab.

If you haven't already, be sure to checkout the Getting Started with OAuth 2.0 page to familiarize yourself with OAuth 2.0.

Security Type

There are two types of OAuth 2.0 client security types: public and confidential. In general, you should decide on the security type of your OAuth 2.0 client before developing your app, as the authorization flow slightly differs between them.

When should I use a public client?

Public clients are best used in front-end only Trello Power-Ups with no back-end component (e.g. no API endpoints, no database). Power-Ups using a public client should be using the Power-Up client library's OAuth 2.0 API client functions to handle authorizing users and fetching access tokens. See our OAuth 2.0 example Power-Up, which showcases how to use a Power-Up with a public client.

When should I use a confidential client?

Confiential clients should be used for Trello apps with a backend component. This includes both Power-Ups and apps that don't use Power-Up capabilities. However, note that confidential clients cannot use the Power-Up client library's OAuth 2.0 API client. See our example confidential client app for more information on how to use confidential clients.

Callback URLs

You must set the callback URLs your OAuth 2.0 client uses for authorization. The value of the redirect_uri parameter in the authorization URL must match one of the app's callback URLs. All callback URLs should be pages under a domain you control, like the domain of your Power-Up or application.

You need at least one callback URL. To add a callback URL, simply enter the URL in the input box, press "Add", then press "Save" once you've made all your changes. You may have multiple callback URLs, which will all be valid values for the redirect_uri parameter.

To see an example of how callback URLs are used during authorization, see the documentation below:

1. For public clients (Power-Up example).
2. For confidential clients.

Scopes

Scopes determine what kind of API actions your OAuth 2.0 client is allowed to do. When authorizing with your users, the scopes you pass in must be included in the scopes configured here. To add or remove scopes from your app, select or deselect scopes from the table, then press "Save" at the bottom of the page. Note that changing the scopes of your client may require you to re-authorize with your users with the new scopes.

Additionally, there are a few other details you should be aware of:

The offline_access special scope

The special scope offline_access does not appear in the client configuration, but must be passed in when manually hitting the authorization endpoint at https://auth.atlassian.com/authorize in order to receive a refresh token. To view an example of the usage of the offline_access scope during the initial authorize call, see our example confidential client app.

If you are building a Power-Up and use t.getOAuth2ApiClient().authorize() for OAuth 2.0 authorization, you do not need to pass in offline_access, as it is passed in for you under the hood. See our OAuth 2.0 example Power-Up, which uses a public client.

Default Scopes

For Power-Ups, the read:board:trello and write:board:trello scopes are always enabled, meaning all access tokens that your app authorizes will always have these scopes. OAuth 2.0 clients of non-Power-Up apps do not have this requirement.

Workspace Restriction

Power-Up OAuth 2.0 clients are workspace-restricted. Certain scope permissions will be limited to a single workspace. This means your Power-Up may need to request authorization multiple times from a single user if they use your Power-Up across different workspaces. OAuth 2.0 clients of non-Power-Up apps do not have this restriction. See the table below for which scopes are affected.