RFC-89: Introducing OAuth2 to Trello

General Request for Comments (RFC)
, ,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Project Summary

We’re replacing Trello’s current authorization mechanism with OAuth 2.0 (3LO) (also known as “three-legged OAuth” or “authorization code grants”). Along with this change we’re introducing new scopes, resource restrictions, and token expiry for greater security.

We will start by adding support for OAuth 2.0 then announce a deprecation of the soon-to-be known as ‘legacy’ Trello User Token and OAuth 1.0 mechanisms. We are not announcing a deprecation at this time so this RFC will not have details on the enforcement policy or a dates for the deprecation.

  • Publish: 14-03-2025
  • Discuss: 11-04-2025
  • Resolve: 30-09-2025

Problem

Trello’s API authorization mechanisms lack the controls and security capabilities that our customers expect.

Today’s Trello User Tokens and OAuth 1.0

  1. allow for tokens that do not expire
  2. have very coarse grained scopes
  3. can not be constrained to specific workspaces
  4. can be supplied within query params

The proposed solution will resolve all of these deficiencies in Trello’s current authorization mechanism.

Proposed Solution

Authorization

We’re adopting OAuth 2.0 - the industry standard protocol for authorization. OAuth 2.0 is already being used by other products at Atlassian.

Authorization Code Grant

All Trello OAuth 2.0 authorization will be performed using Authorization Code Grants.

PKCE

Proof Key for Code Exchange (PKCE), an extension to the Authorization Code flow, will be required to prevent CSRF and authorization code injection attacks.

All Trello OAuth2 authorization will require PKCE.

Refresh Token

Today Trello tokens have an optional expiry. Trello OAuth2 tokens will always enforce expiry. The Authorization Code Grant will issue refresh tokens alongside short-lived access tokens. The refresh token will allow power-ups to request a fresh access token and refresh token without requiring action or approval by the user. Refresh tokens are valid until they are explicitly revoked or expired.

Access tokens expire after 1 hour, refresh tokens expire after 30 days.

HTTP Request with Bearer Token

Trello’s API will accept access tokens as bearer token via the HTTP Authorization header.

Example:

GET /1/member/me HTTP/1.1
Host: trello.com
Authorization: Bearer <access_token>

Scopes

In addition to OAuth 2.0 we are also introducing new scopes. These scopes provide you with more granularity to specify only the permissions your power-up needs and offers our customers greater confidence that their data is protected.

The new scopes include:

  • read:board:trello
    • Read list fields
    • Read card fields and data. This includes:
      • checklists
      • comments
      • attachments
      • emojis
      • stickers
      • dates
      • labels
  • read:organization:trello
    • Read workspace fields and settings
    • Read workspace boards and memberships
    • Read all power-ups managed by the consenting user
  • read:enterprise:trello
    • Read enterprises fields and settings
  • write:board:trello
    • Create and update all list and card level data on boards.
    • Update board preferences on permissions level, comments, invitations, self join, etc.
    • Make comments on behalf of the user
    • Delete boards
    • Delete lists and cards
  • write:organization:trello
    • Create and update workspaces
    • Delete workspaces
    • Update workspace permissions level preferences
    • Update Power-ups on behalf of the user
  • write:enterprise:trello
    • Update and manage Enterprises
  • read:member:trello
    • Read the user’s email address
    • See user’s board, workspace, and enterprise memberships
    • See public name and avatar
  • write:member:trello
    • Add the user to self-join boards & organizations
    • Upload member-level assets: custom stickers, emojis, board backgrounds

Once the granularity of these scopes are agreed upon, a complete API mapping will be made available in Trello’s REST API documentation.

Resource Restrictions

Power-ups are installed on a workspace. When a user authorizes a power-up they do so within the context of the workspace where the power-up is installed. The resulting OAuth 2.0 access_token is restricted such that only resources within the workspace are accessible. This restriction is applied in addition to scopes which are described above.

Integrations which are installed outside of the power-up installation flow will have no such workspace restriction.

Further Changes

We will be deprecating Trello’s existing auth mechanisms at a future date. This includes both token based authorization using 1/authorize as well as OAuth 1.0.

Once Trello has launched OAuth 2.0 there will be another announcement detailing the deprecation timeline.

Asks

While we appreciate any reactions you have to this RFC, we’re especially interested in learning more about:

  • Do you see any challenges that the proposed changes to authorization, scopes, resource restrictions, and / or token expiry fail to address?
  • Do you have concerns about token expiry?
  • Would you like us to introduce any other scopes, and why?
2

What’s the rational behind totally abandoning user API Tokens? Why not just make user API Tokens time limited in lifespan, like what was done with Jira / Confluence API Tokens? Are they really that evil?

Have you considered the effect on all those Trello automations that are dependent on API Tokens with the HTTP Request action to perform tasks? That part of Trello will need to be changed and every single automation on the planet that uses an API Token will need to be re-built.

2 Likes
3

Hi @sunnyape - Can you be more specific about the types of automations you’re talking about? Are you referring to ~Jira Automations that integrate with Trello or other types of integrations that perform automation like actions (e.g. Zapier) or are you referring to some custom automations built using Trello Automations?

4

Yep, Trello’s built-in automations; the thing that used to be called Butler.

The HTTP Requests action requires a key + token to be manually put in the request body or path to send requests to Trello (or any other system’s) REST API that supports Basic Auth.

It has no OAuth support, so all HTTP Request actions that interact with Trello would cease to work if Basic Auth was deprecated.

1 Like
5

I really like the idea of more fine grained scopes. The APIs right now provide way to much access when you only need the basics inside the powerup.

A few things I would ask about or recommend:

  1. Will the client.authorize() method still work or have an equivalent?

See: https://developer.atlassian.com/cloud/trello/power-ups/rest-api-client/

Having something simple like this for powerups to use that “just works” and keeps track of the tokens internal to Trello managed code is the best way to go for most powerups in my opinion. This way there is no need for the powerup developer to have access to and store any tokens.

I know that right now there are issues because using local storage inside the iframe is limited similar to third-party cookies. But if there was some way Trello could work around this that would work with browsers that have tighened security, that would be perfect.

  1. Users don’t understand tokens, auth, and often go long periods without accessing boards

Whatever is done needs to be as transparent to users as possible. I have found over and over that the standard Trello user doesn’t really understand why powerups need authorization and once it is authorized they don’t understand why things don’t show up if the authorization needs granted again. To the extend possible I suggest the REST API Client that powerups use should simply handle the token refresh automatically internal to the REST Client such that powerups can effectively “just work” once authorize() is called.

  1. Provide an API that makes it easier to know when the REST API is not authorized vs when a token has expired.

This would make it easier for powerups to present a friendly UI about what needs to be done and why. Right now IIUC, both of those cases show up as “client.isAuthorized()” returning false.

Again, overall I think this is a great improvement. Just want to ensure that the simple wrapper exists to help powerup developers work through it quickly and easily.

-Allen

6

While I like the idea of new scopes and needing to get shortlived “access tokens”, having “refresh tokens” that expire is quite annoying (and setting it as low as 30 days would be especially ignoring!)

Why not instead make the refresh token expire-date configurable/optional when issued like so many others do? That way PowerUps can choose a non-expiring or say 3-month refresh token so users that use the tool very infrequently are forced to auth every time.

As for the scopes, please consider that it should be possible to retrieve what scopes a given token has so we who build APIs and are just given an API Key and Token today (API + Refresh-token in the future) can look up the granted scopes using the API.

7

I share the same concern as @sunnyape

Besides http request from Trello automation, you have backend inbound messages using Trello api or wrappers providing services to integrate with Trello boards.

In the case of GHL, they have transited to Oauth2 for their API2.0 However they provide private integration with scope for use as well. The refresh is manual and I found that to be useful. For apps, Oauth2.0 scheme will be used but the refresh token has a much longer expiry.

2 Likes
8

Thanks @RasmusWulffJensen. To protect the security of our customers we will no longer provide long lived tokens. Would allowing refresh token up to 90 days alleviate your concerns?

9

@SGiAdmin - We have taken into consideration how this impacts integrations that take actions thru a single API token and recognize this will require a change from our developer community. We’d like to make the migration as easy as possible, however to protect the security of our customers we will no longer provide long lived tokens. This type of “single user” integration will need to use the refresh token to fetch a fresh access_token on the expiry cadence. We recognize this adds complexity to integrating with Trello and plan to document some examples of different integration types. If you can provide example architectures that are particularly impacted, we can incorporate that in our example documentation.

10

Here I am talking about FastAPI using py-trello to provide more complex Trello services receiving POST, GET, …etc requests. They can service http request from Trello automation or from external services. Currently there is a client that uses the api key and token. Granted that the maintainer will have to change the code. So provisions had to be made for use in type cases.

11

3 months are better than 1 month, but still on the low end:

Examples from other services i have used over the years

Github Access Tokens: You can fully confige number of days and even Never (with a warning though that it is not recommended)

Google APIs: Refresh tokens never expirer

Azure App Registration Secrets: 180 days recommended but up to 24 months

Microsoft Graph: 90 days (and refresh tokens auto-renew on usage)

Strava API: Refresh token never expire

Zendesk: Token never expirer

Star Certificates: 12 months

Slack Tokens: Never Expirer

So as you can see almost all other services do not set expiry so low, and the really good ones make it configurable so it fit all levels of need for security levels

12

Please don’t shut down the current API tokens. If your concern is that the current auth mechanism doesn’t have what your customers expect, then please add it in addition to the current API tokens.

If you go ahead with this I will need to shut down BenkoBot, BenkoBoard and BenkoDesk, as well as disconnecting the BenkoPhone Trello integration. I will have to turn off the Trellinator webhooks and tell people they can no longer use the project.

These are all legacy projects upon which people still rely but do not generate any growth or significant income that would justify the investment in retooling the authentication everywhere.

I would most likely move away from Trello also, and would encourage my clients to do the same, depending on how difficult it would be for me to invest in updating the authentication mechanisms for my own specific automation use cases.

Thanks,
Iain

2 Likes
13

This is utterly ridiculous. Some unknown customers want you to abandon the current API’s basic auth for something else, and you just decided to do it? At our company, we have hundreds of automations that have transformed our Trello into a state-of-the-art management system. We’ve spent months building it, and suddenly, you’re shutting it down for no good reason, and it is deeply concerning to us.

I don’t know if this is fully decided or not, BUT PLEASE DO NOT ABANDON BASIC AUTH or at least do not expire current tokens.

1 Like
14

Hi @akassab
Please reconsider this decision and make it optional. I agree with @IainDooley that much time, effort, and investment have been spent on Trello automations. I would greatly appreciate it if you could leave the current API in place.