Skip to main content

Trello

Trello is a personal integration — you connect it with your own Trello account, and it gives Companion access to your boards so action items and follow-ups can become cards without leaving a conversation.

Most personal integrations use OAuth, where you just click Connect and sign in. Trello is one of the ones that doesn't: its REST API authenticates with an API key plus an API token, and you generate both yourself. To do that you register a Trello Power-Up app, take the API key it generates, manually generate a token from that app, and paste both values into Harmony.

This is a per-user setup — you do not need integrations:write:all or any other workspace permission, and nothing you do here affects other people in your workspace. The key and token belong to the Trello account you authorize with, so sign in with the account that already has access to the boards you want Companion to work with. Everyone who wants Trello in Harmony repeats these steps with their own account.

Step 1. Create a Trello Power-Up app​

Sign in to Trello and open the Power-Up admin portal. Click New to create an app, then fill in the form:

  • App name — a recognizable name, for example HeyHarmony.
  • Workspace — the Trello Workspace the app belongs to. Admins of that Workspace and the app's collaborators can manage it, and if you ever leave the Workspace you lose access to the app — so choose a Workspace you expect to stay in.
  • Email — an address Trello can use to reach you about the app.
  • Support contact — an email or support link for your users.
  • Author — your company name (or your own name if you are not part of an organization).
  • Iframe connector URL — leave this empty. It is only needed for Power-Ups that render UI inside Trello; Harmony uses the REST API, not an iframe connector.

Click Create.

Step 2. Generate the API key​

Open the app you just created and select API key in the left-hand menu, then generate a key. This is the value Harmony uses to identify the application.

While you are on this page:

  • Copy the API key — you will paste it into Harmony in Step 5.
  • Add the allowed origin https://app.heyharmony.com under Allowed origins, then click Add. Trello blocks redirects back to any origin that is not listed here.
  • Ignore the Secret — the Secret is only used for Trello's OAuth 1 flow. Harmony authenticates with an API key and token, so you do not need it.

Then, in the panel on the right, click the Token link ("…you can manually generate a Token"). This starts the authorization flow that produces your API token.

The Token link opens Trello's authorize page. Its URL accepts scope (read, write, account) and expiration (1hour, 1day, 30days, never) parameters. Harmony needs both read and write access to create and update cards. If you set a finite expiration, the integration stops working when the token expires and you will have to repeat Steps 2–5 to issue a new one.

Step 3. Approve the authorization request​

Trello shows exactly what the app will be able to do — read your name, username, and email, read your boards and Workspaces, create and update cards, lists, boards, and Workspaces, and read or update Power-Ups you own. It also lists which boards and Workspaces the app will have access to.

Review the list and click Allow.

The token grants access to every board and Workspace the authorizing Trello account can reach — including boards that account gains access to in the future. Authorize with an account whose board access matches what you want Harmony to see.

Step 4. Copy the API token​

After approving, Trello displays the generated token on a confirmation page. Copy the full value.

The token is shown on this page only — Trello does not display it again. Anyone holding the API key and token can act on your Trello account with the permissions you just approved. Never send it over email or chat, and never paste it anywhere other than the Harmony setup form. If it leaks, revoke it from your Trello account's Applications settings and generate a new one.

Step 5. Paste the credentials into Harmony​

Back in Harmony, open Marketplace from the sidebar, select the Trello tile in the Apps tab, and click Connect. Instead of an OAuth sign-in, Trello asks for the two values you just generated. Paste:

  1. The API key from Step 2.
  2. The API token from Step 4.

Then save. Harmony validates the credentials against Trello before storing them, so a save that succeeds means the pair works.

Once saved, Trello capabilities are enabled and exposed to Companion, so you can ask it to look up boards and cards or turn action items into Trello cards — with confirmation before anything is written back. The connection is yours alone: it appears under Marketplace → Installed for you, and other people in the workspace do not inherit it. See Companion apps for how Companion tools work, and Personal integrations for managing or removing it later.

Troubleshooting​

  • Saving fails with an authentication error — the key and token must come from the same Power-Up app. If you regenerated the API key after issuing the token, the old token is no longer valid; generate a new token from Step 2.
  • The Token link redirects to an error page — https://app.heyharmony.com is missing from Allowed origins on the API key page. Add it and retry.
  • The integration worked and then stopped — the token most likely expired. Tokens generated with a finite expiration stop working silently; repeat Steps 2–5 with expiration=never if your security policy allows it.
  • Companion can't see a board — the board is not visible to the Trello account that authorized the token. Add that account to the board in Trello, or re-issue the token from an account that already has access.
  • You need to revoke access — open your Trello account's Applications settings and revoke the token, or delete the Power-Up app from the admin portal. Both immediately break the Harmony connection until new credentials are saved.