Trello Developers

Authorization

Introduction

Trello's API uses token-based authentication to grant third-party applications access to the Trello API. Once a Trello user has granted an application access to their Trello account and data, the application is given a token that can be used to make requests to the Trello API on behalf of the user.

There are two ways to authorize a client and receive a User Token. The first is via our authorize route, the second is via basic OAuth1.0. We'll cover the former now. If you'd rather use OAuth, you can skip ahead to Using Basic OAuth.

Authorizing A Client

To begin the authentication process, you need an API key. Every Trello user is given an API key. You can retrieve your API key by logging into Trello and visiting https://trello.com/app-key/.

Because the API key is tied to the user, it is often a good idea to create a Trello user specifically for building a single application or integration. This ensures that a third-party's integration is disassociated from a third-party integration's developer's Trello account.

Once you have an API key, you will use it to ask a Trello user to grant access to your application. To do so, you should direct a user to the authorize URL and pass along the query parameters needed as documented below. The authorize prompt can be opened in a number of different ways and with a number of different options.

When you kick off the authorization flow, the user will see the following screen:

The name of the application, length of access, and scope of permissions are all configurable via query params (documented below).

For instance, if you're just getting started with Trello's API and you'd like to explore what is possible, you can generate a token for yourself using your API key and the following URL:
https://trello.com/1/authorize?expiration=1day&name=MyPersonalToken&scope=read&response_type=token&key={YourAPIKey}

After visiting this page and clicking the green Allow button, you'll be redirected to a page with your token. You can now use that token and your API key to make a request to the Trello API. You can give it a try with: https://api.trello.com/1/members/me/?key={yourAPIKey}&token={yourAPIToken}. This should return an object containing information about your Trello user.

Keep Trello Tokens Secret

Tokens for users should always be securely stored as they grant access to the entire user's account! It is ok for your API key to be publicly available, but a token should never be publicly available. If a token becomes public, it should be revoked immediately by the user.

If you’re authorizing a web client, you may want to check out client.js, a wrapper for the API in javascript. It includes built-in authorization methods that you may find useful. However, it uses the same route as is documented below.

1/authorize/ Route Options

Paramer
Valid Values
Description

callback_method
string

postMessage or fragment

Defines how the token is returned to you. Generally, postMessage is used if the authorization is done in a popup, and fragment if it is done by redirect. For details on how to use these, see client.js.

return_url
string

A valid URL that the token should be returned to.

If the token is being passed by fragment, this is where the user will be redirected after authorization.

If the token is being passed by postMessage, this will be used as the origin for the postMessage.

scope
string

Comma-separated list of one or more of read, write, account.

Read: reading of boards, organizations, etc. on behalf of the user

Write: writing of boards, organizations, etc. on behalf of the user

Account: writing of member info, and marking notifications read

expiration
string

1hour, 1day, 30days, never

When the token should expire.

name
string

Name of the application.

Displayed during the authorization process

key
string

Used to generate the user's token.

response_type
string

token or fragment

The response_type of token will return the full user token.

Revoking Tokens

Trello users can view metadata regarding the applications they have authorized and granted a token by visiting their account settings page: https://trello.com/{username}/account. There, under the Applications heading, they will see a list of every application they've granted access to, the scope of the access, the date access was approved, and the date that the token expires.

Users are able to revoke a token by clicking on the Revoke button next to the listing. Revoking the token removes the token's access to the user's account and it can no longer be used to make requests to Trello's API on behalf of the user.

Tokens can also be deleted via the API. There is a /1/tokens resource that includes a DELETE action documented at: https://developers.trello.com/reference#tokenstoken-1

Applications and Power-Ups should handle token revocation gracefully. If a token has been revoked, the API will respond with a 401 HTTP status and the message: invalid token. At that point in time, the Power-Up or integration should ask the user to re-authorize the application.

Using Basic OAuth

The Trello API supports basic OAuth 1.0; you can use an OAuth library and the following URLs:

https://trello.com/1/OAuthGetRequestToken
https://trello.com/1/OAuthAuthorizeToken
https://trello.com/1/OAuthGetAccessToken

You’ll also need your application secret (used to sign your requests). That’s listed in the second box on https://trello.com/app-key.

Example OAuth Project In Node.js

We've put together an example project in node that demonstrates the basic routes and configuration necessary to use OAuth to access Trello's API. You can view the Glitch project here.