Skip to content
Rack API and Rails Engine for Heroku and Opperator add-ons
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Maître d’

Rack APIs powered by Grape for managing Heroku and CloudControl add-ons.

Maître d’ manages all the authorisation checking for API requests and provides simple hooks for you to write just the code you need to handle provisioning, plan changes, deprovisioning and single-sign-on (SSO) requests.


Add the following to your Gemfile:

gem 'maitre_d', '~> 0.5.0'

With Rails

Add the appropriate Rack apps to your routes file:

# if you're supporting Heroku
mount       => '/heroku'
# if you're supporting CloudControl
mount => '/cloudcontrol'

Without Rails

As shown above, you can use Maître d’ Rack API for both Heroku and Cloud Control. Mount them to wherever you see fit. Once upon a time Heroku expected its endpoints to be at /heroku, but now things are a little more flexible.


You’ll need to provide Maître d’ with the appropriate provider credentials – in a Rails app, this would go in an initializer, but for Rack/Sinatra apps just get the values set before the routing is defined.

require 'maitre_d/heroku'

MaitreD::Heroku.configure do |config|       = 'addon-id'
  config.password = 'random'
  config.sso_salt = 'gibberish'
  config.listener = HerokuListener

require 'maitre_d/cloud_control'

MaitreD::CloudControl.configure do |config|       = 'addon-id'
  config.password = 'random'
  config.sso_salt = 'gibberish'
  config.listener = CloudControlListener

The listeners that are mentioned in the code above are classes, which will handle valid API requests. Read on for more details on how to set them up.


Your listener classes should handle the following four methods:

provision(heroku_id, plan, region, callback_url, logplex_token, options)

This gets called when the provider is requesting an app be provisioned within your service, and expects a hash to be returned with the following keys:

Your local resource id, which the provider will use in related requests (to change plans, deprovision or initialise single-sign-on).
A hash of the newly provisioned resource’s configuration values (that are provided as environment variables to the app in question).
An optional message that will be displayed when your add-on is added via the command-line.

plan_change(resource_id, heroku_id, plan)

This gets called when an app is upgrading or downgrading from their current plan. You need to return a hash with the following keys:

A hash of the modified resource’s configuration values (that are provided as environment variables to the app in question).
An optional message that will be displayed when an app using your add-on is upgraded or downgraded via the command-line.


This gets called when an app is removing your add-on from itself. You don’t have to return anything in particular for this, though Heroku may pass through the message argument like it does for the provision and plan_change calls.


Maître d’ will check the token and timestamp provided, and sets up the nav-data cookie, but you’ll need to decide where the user gets redirected to and what other details you wish to track via their session. To do this, just return a hash with the following keys:

The URI to redirect the user to, now that you’ve signed them in.
A hash of any session values you wish to be set.

Here’s a very basic example:

class HerokuListener
  def provision(heroku_id, plan, region, callback_url, logplex_token, options)
    plan   = Plan.find_by_name plan
    widget = Widget.create(
      :heroku_id    => heroku_id,
      :callback_url => callback_url,
      :plan         => plan,
      :region       => region

      :id      =>,
      :config  => {'WIDGET_KEY' => widget.key},
      :message => 'Add-on provisioned!'

  def plan_change(resource_id, heroku_id, plan)
    plan   = Plan.find_by_name plan
    widget = Widget.find resource_id
    widget.plan = plan

    {:config => {'WIDGET_KEY' => widget.key}}

  def deprovision(resource_id)
    widget = Widget.find resource_id

  def single_sign_on(resource_id)
    widget = Widget.find resource_id

      :uri     => '/my/dashboard',
      :session => {:widget_id =>}

You can have the listener class wherever you like – as long as it’s available within the context of your Rails/Rack site, it’ll work as expected.


Contributions are very much welcome – but keep in mind the following:

  • Keep patches in a separate branch.
  • Write tests for your patches.
  • Don’t mess with the version or history file. I’ll take care of that when the patch is merged in.


Copyright © 2011-2015, Maître d’ is developed and maintained by Pat Allan, and is released under the open MIT Licence.

Something went wrong with that request. Please try again.