OAuth 2.0 For Existing Apps

This guide walks you through the steps to add an OAuth 2.0 client to your Trello app, choose an authorization flow, and migrate existing users from Trello Auth tokens to OAuth 2.0 tokens.

If you're new to Trello OAuth 2.0, start with the Getting Started with OAuth 2.0 page for an overview of how it works and an example Power-Up you can clone.

Is OAuth 2.0 right for my app?

Trello's OAuth 2.0 3LO protocol (also known as "three-legged OAuth" or "authorization code grants") is the right choice for user-facing apps where a person logs in and consents to access. Your app can then access the Trello API on behalf of that user.

If that describes your app, then we recommend OAuth 2.0 as the most flexible and secure way for your app to access the Trello API. If your app does not run on behalf of a logged-in user (bots, automation, or server-to-server integrations), then OAuth 2.0 may not be the ideal authorization mechanism.

Step 1: Configure your OAuth 2.0 client

Navigate to your Trello app in the Trello apps administration page and click the OAuth 2.0 tab to create and configure your client. If you haven't created an app yet, then visit the OAuth 2.0 Getting Started page to get started with our example OAuth 2.0 Power-Up.

You'll need to configure a security type, callback URLs, and scopes. See OAuth 2.0 Client Configuration for full details on each of these settings.

Step 2: Implement the authorization flow

How you implement authorization depends on whether your OAuth 2.0 client is public or confidential. See the security type documentation for help choosing between them.

• Public client (front-end only Power-Ups): Use the Power-Up client library's OAuth 2.0 API client, which handles PKCE, authorization code exchange, token storage, and token refresh for you.
• Confidential client (Apps with a backend): Follow the OAuth 2.0 Confidential Client Usage guide to handle the authorization code exchange and token refresh yourself.

Migrating existing users with token exchange (recommended)

Because your app already has users authorized with Trello Auth tokens, we strongly recommend pairing your new authorization flow with the token exchange flow. Token exchange takes a user's existing Trello Auth token and swaps it for a new set of OAuth 2.0 tokens, so your existing users can keep using your app without re-authorizing in the OAuth 2.0 consent screen.

Follow the detailed token exchange instructions for the type of OAuth 2.0 client you configured in Step 1:

• Public client (front-end only Power-Ups): Read about token exchange with the OAuth 2.0 API client for Power-Up instructions. The OAuth 2.0 API client performs the exchange and stores the new tokens in plugin data for you.
• Confidential client (apps with a backend): Read about token exchange with the POST /1/token/exchange endpoint for instructions on performing token exchange with a secure backend.

A few important things to know before implementing it:

• The original Trello Auth token is revoked as part of the exchange and can no longer be used to call the Trello API. After the exchange, all Trello API requests for that user must use the new OAuth 2.0 access token (passed as a bearer token).
• For Power-Up clients, the new OAuth 2.0 token is workspace-restricted to the workspace the user is currently in. If your users use your Power-Up across multiple workspaces, only the first workspace can be migrated this way. For every other workspace, you'll need to fall back to the standard OAuth 2.0 authorization flow so the user can consent to that workspace.

Step 3: Set up compliance polling

If your Power-Up stores personal data, you must comply with Trello's data privacy requirements. With an OAuth 2.0 client, you use your client credentials to authenticate with the compliance polling API instead of a Trello Auth API secret.

See Personal Data Storage and GDPR for the full compliance requirements, including how to poll with OAuth 2.0 credentials.

Further Reading

Be sure to checkout our other documentation to learn more about OAuth 2.0.

1. Getting Started with OAuth 2.0 - Overview and example Power-Up.
2. OAuth 2.0 Client Configuration - Dive deeper into the different parts of the OAuth 2.0 client configuration.
3. OAuth 2.0 API Client for Power-Ups - Read documentation on how to use OAuth 2.0 with Power-Ups.
4. OAuth 2.0 Confidential Client Usage - Learn how to create a Trello app with a confidential client.
5. Personal Data Storage and GDPR - Learn about compliance polling requirements for apps that store personal data.