Rate this page:
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 1/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.
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.
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.
Parameter | Valid Values | Description |
---|---|---|
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. |
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. |
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: read member email, 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 | Valid Trello API key. | Used to generate the user's token. |
response_type string | token or fragment | The response_type of token will return the full user token. |
Depending on the response_type
you are using, Trello will do one of two things when a user clicks "Deny" from the authorization flow's prompt.
response_type | Trello's Response |
---|---|
fragment | Trello will now add an empty token= query parameter and error= parameter with error message to the fragment when redirecting back to the return_url specified. |
postMessage | Trello will postMessage an error key in the postMessage with the error message being the value. This will be sent to the return_url specified. |
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.
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.
When your application is authenticating a user, you may provide a return_url
that Trello will redirect to after the user gives consent for your application. By default an application key can redirect to any domain, but we strongly recommend that you specify the origins that your application will redirect to when completing authorization.
For example, if we were GitHub building a GitHub integration for Trello, and we know we will only ever redirect back to https://github.com
after the user grants access in the auth flow, or perhaps also http://localhost:3000
for local development, we could add both of those as allowed origins for our application, and no one will be able to use our API key to authenticate users and pass back the token to any other URLs, like https://bad.example.com
.
You can view and edit your application's allowed origins at: https://trello.com/app-key.
Note: If your API key has no allowed origins set, then no redirect URL will work. By default, all API keys will have a wildcard *
allowed origin which permits any URL to be used.
The Application Icon
section includes an input field into which you can save the URL of the icon that you would like to use.
The icon you submit will be used to replace the placeholder icon found on the authorization flow. If no icon is submitted, we'll continue to show the default icon.
The icon should be 64px by 64px and hosted on https://
.
The Trello API supports basic OAuth 1.0; you can use an OAuth library and the following URLs:
1 2 3
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.
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.
Once you have an API key and a user's token, you can pass authorization information to Trello one of three ways:
Authorization
headerThe easiest and quickest way to pass authorization to Trello is via query parameters.
You can include a key=
and token=
query parameter in your request.
For instance, here is a simple request passing authorization via query parameters:
1
curl https://api.trello.com/1/members/me?key={{apiKey}}&token={{apiToken}}
Authorization
headerThe Trello API will also accept authorization via an Authorization
header
with the format: OAuth oauth_consumer_key="{{apiKey}}", oauth_token="{{apiToken}}"
.
For instance, here is the same request as above, but using an Authorization
header:
1
curl -H "Authorization: OAuth oauth_consumer_key=\"{{apiKey}}\", oauth_token=\"{{apiToken}}\"" https://api.trello.com/1/members/me
If you are making a PUT or POST request to Trello's API, you may also include the key and token in the request's body:
1 2 3 4
curl -X PUT \
https://api.trello.com/1/cards/5e568d33e9b5e88bb99996d0/name \
-H "Content-Type: application/json" \
-d '{"key": "{{apiKey}}", "token": "{{apiToken}}", "value": "Finish Final Presentation" }'
Rate this page: