Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.

ExTrello Build StatusCoverage DownloadsDeps StatusInline docs

A library for interfacing with the Trello API.

Heavily influenced by with some stuff straight ripped out of it.

Important! Migration from 0.x -> 1.x

Since this change will break all existing projects using ExTrello upon upgrading this deserves a spot at the top :)

All calls to the Trello API will now be wrapped in a tuple with the first element either being :ok, :error, or :connection_error Regular errors will no longer raise exceptions as that is not idiomatic.

Here's an example(just a little sample):

# Old and bad
boards = ExTrello.boards()
# New and great
{:ok, boards} = ExTrello.boards()

# Old and bad, yuck!
try do
  %ExTrello.Error{code: code, message: message} -> IO.puts "ERROR[#{code}] - #{message}"

# New and fantastic
case ExTrello.get("potato/2") do
  {:ok, response} -> response
  {:error, %ExTrello.Error{code: code, message: message}} -> IO.puts "ERROR[#{code}] - #{message}"
  {:connection_error, %ExTrello.ConnectionError{reason: _, message: message}} -> IO.puts "#{message} We should retry."



  1. Add ex_trello to your list of dependencies in mix.exs:
def deps do
    {:ex_trello, "~> 1.1.0"}
  1. Ensure ex_trello is started before your application:
def application do
  [applications: [:ex_trello]]
  1. Run mix deps.get


  1. Make sure you've completed installation.
  2. Use ExTrello.configure to setup Trello's OAuth authentication parameters.
  3. Call functions in the ExTrello module. (e.g. ExTrello.boards())


The default behavior is for ExTrello to use the application environment:

In config/<env>.exs add:

# I like using ENV vars to populate my configuration. But fill this out however you'd like :)
config :ex_trello, :oauth, [
  consumer_key:    System.get_env("TRELLO_CONSUMER_KEY"),
  consumer_secret: System.get_env("TRELLO_CONSUMER_SECRET"),
  token:           System.get_env("TRELLO_ACCESS_TOKEN"),
  token_secret:    System.get_env("TRELLO_ACCESS_SECRET")

You can also manually configure it at runtime:

ExTrello.configure(consumer_key: "...", ...)

You can also configure for the current process only:

defmodule TrelloServer do
  use GenServer

  def start_link(user) do
    GenServer.start_link(__MODULE__, user, [])

  def init(%User{token: token, token_secret: token_secret}) do
    :ok = ExTrello.configure(
      consumer_key: System.get_env("TRELLO_CONSUMER_KEY"),
      consumer_secret: System.get_env("TRELLO_CONSUMER_SECRET"),
      token: token,
      token_secret: token_secret
    {:ok, %{boards: []}}

  # Rest of your code...


Authorize your application

Example for authorization. This is a naive solution that only works for demonstration. TODO: Set up example application.

# First we have to get a request token from Trello.
{:ok, token} = ExTrello.request_token("http://localhost:4000/auth/trello/callback/1234")
# We have to store this token because we need the `oauth_token_secret` after the callback to obtain our access token & secret.
# e.g."1234", token.oauth_token_secret)

# Generate the url for authorization
{:ok, auth_url} = ExTrello.authorize_url(token.oauth_token, %{return_url: "http://localhost:4000/auth/trello/callback/1234", scope: "read,write", expiration: "never", name: "Your Application Name here"})

# Copy the url and visit it using your browser.
IO.puts auth_url

After signing in/authorizing the application you will be redirected to the callback URL you specified in the Request token & authorize URL.



Copy the oauth_token and oauth_verifier above:

oauth_token = "copied_oauth_token"
oauth_verifier = "copied_oauth_verifier"
oauth_token_secret = retrieve_oauth_token_secret_from_before() # e.g. TokenAgent.retrieve("1234") from hypothetical TokenAgent

{:ok, access_token} = ExTrello.access_token(oauth_verifier, oauth_token, oauth_token_secret)

# Let's configure ExTrello with our newly obtained access token
  consumer_key: System.get_env("TRELLO_CONSUMER_KEY"),
  consumer_secret: System.get_env("TRELLO_CONSUMER_SECRET"),
  token: access_token.oauth_token,
  token_secret: access_token.oauth_token_secret

# Testing our token!
{:ok, member} = ExTrello.member() # Fetches the authenticated member record from Trello


  • Add models for label, checklist, member, notification, organization, session, token, action
  • Pagination
  • Code Cleanup! (Perhaps remove defapicall macro and use the with keyword instead? Have to evaluate.)
  • Example Application
  • Investigate handling storage of request_token.oauth_token_secret instead of leaving that up to the dev.