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.

1 Like
15

Update from Trello

Thank you all for spending time to provide feedback on this RFC. The Trello team has taken this feedback and have spent some time investigating options. Apologies for the delayed communication here, we want to ensure we’re evaluating our options to provide the best solutions to our customers.

I want to reiterate that this post is not a deprecation notice. Trello does intend to eventually deprecate the current AppKey/Token auth solution, but first we must provide new capabilities to replace all the various ways that AppKey/Tokens are used today. Once these new capabilities are available we will announce a deprecation timeline here and on the Trello changelog.

We are continuing to develop OAuth 2.0 3LO mostly as described above. Below are some adjustments and related proposals where again, we seek community feedback.

Non-3LO Offerings

First and perhaps most importantly, I want to recognize that OAuth 2.0 3LO does not adequately cover all use cases for our current AppKey/Token offering. We are exploring how to best support API tokens like those offered by other Atlassian products. As @sunnyape astutely points out, API tokens are not evil. Atlassian API tokens will offer scopes as described above and will be time limited, configurable up to a year. They will provide advantages over our current AppKey/Token solution such as narrower access and improved visibility while maintaining the flexibility and ease of use of Trello’s current AppKey/Tokens.

Automation

Quite a few of the comments here are about Trello token use within Trello automation. We are exploring how we might make automation use cases retain the flexibility of HTTP Request but without the need to provide an API token. Automation is a feature of Trello and should not require users to provision an API token to use it fully. In this exploration we are determining the viability of migrating existing automation rules that follow this pattern to preserve the countless hours of effort our users have put into customizing Trello via automation. The Trello team needs to dig a little into how customers are using API tokens within automation, more on this in a future update. At minimum there should be a migration path for end-users to replace Trello API tokens with Atlassian API tokens, as mentioned above, but we will continue to investigate ways to remove the need for an API token to be set into automation rules at all.

Refresh Token Expiry

For the OAuth 2.0 3LO solution itself, we recognize the benefit of longer lived refresh tokens. As @akassab mentioned in another comment, we plan to set the expiry at 90 days and are looking into both configurable values and longer expiry. Every long lived token presents some amount of risk. Thank you for the extra effort on your analysis @RasmusWulffJensen. With the updated guidance here that API tokens will be handled differently, and an update that Trello intends to provide “rotating” refresh tokens, 90 day will continue to be the plan. We are trying to balance ease for both customers and developers with the security of customer’s data and are seeking the right balance. Acknowledging that not all customers fully understand the implications of OAuth consent, it is our duty to be good stewards of their data.

client.authorization()

Trello aims to keep the client.authorization() route as close to “just works” as possible. We are currently investigating how we can provide a similar developer and user experience as we have today.

16

@IainDooley - We are not announcing deprecation of API tokens at this time. We understand that deprecation will impact your business as well as many others and are carefully considering how to proceed. Our aim here is to make it as easy as possible to move from the current AppKey/Token to more modern mechanisms and to provide our customers and partners ample time to do so. We will only announce deprecation once we have confidence that our new mechanisms satisfy customer and partner needs. A change of this magnitude would warrant at least 6 months of deprecation timeline and wouldn’t begin until after the new solutions are available for use.

17

@Alireza1 and @KoosVis - This is not a deprecation announcement and we certainly do not intend to suddenly shut anything down. Any future deprecations will be available on the Trello changelog and will have appropriately early notice. We are seeking to provide a more secure platform for all of our customers, and sometimes this requires breaking changes. As I’m sure you are aware, maintaining legacy systems is not without cost or risk. We can not commit to providing a particular mechanism indefinitely, but we do commit to open communication, customer focused decisions, and providing notices about deprecation timelines relative to the impact.

In seeking to make sure we’re delivering the best alternatives to the existing solution, can you elaborate on your automations? Are these cases such as those mentioned above by @sunnyape or are you referring more generically to custom applications that utilize the Trello API using API key/token pairs?

18

Hi Steve. You mention that the refresh token will have a 90 day expiry (sad but fair)… But you also say that the refresh tokens will be rotating refresh tokens (meaning they can only be used ones I assume (aka a new refresh token is provided together with the short lived access token, and the old can never be used again)… If that is the case then that is truly bad (in many security application setups like example Azure Key Vault it is common practice that the App only have read access to the refresh token, and a higher tier admin system is the only system that can add/update the vault)… If a refresh token is one time only you need to open the app up to writing to the vault and if that update back fails due to example network issue, you are forced restart the entire auth flow.

A better solution is to do like MS Graph if you insist on the 90 days, in that you when requesting the access token get a fresh new 90 day refresh token as well, but the old refresh token is not invalidated and can be used for its entire 90 day lifespan. That mean manual intervention every 3 month to get a new refesh token every 90 days through the higher security tier (annoying but possible), and in cases where app is allowed to write back to its vault, it have 90 days to write back instead of the one chance only scenario

19

Hi Steve,

If you force a move to OAuth2 with refresh tokens it means a major change of multiple legacy systems upon which multiple businesses currently rely, but for no additional benefit (security or otherwise).

They won’t have the money to pay for this rewrite and I don’t want to do it for free, so they will just die.

If your goal is to provide customers with additional scopes and expiry then you can surely add that in addition to the current tokens.

It’s not like companies that have OAuth2 can’t have long lived tokens with full read/write access, you just wouldn’t make it the default.

What I’m asking is for you to keep the current system in tact and add in a more secure default option that provides enterprises with the type of authentication that they are asking for.

For example I was working with a company who uses Wrike. Wrike has the type of OAuth2 you are describing, but they also have a permanent admin token option that works the same as Trello’s current system.

Thanks
Iain

1 Like
20

Hi Steve.
Thank you for the explanation. We use the tools as described by @IainDooley in his previous message.
Thanks
Koos