Rails Quickstart

This guide builds the Quickstart flow into a Rails app with the BundleUp Ruby SDK. A user clicks Connect GitHub, authorizes on GitHub, and lands back in your app, which exchanges the one-time code for a connection_id and lists their repositories through the Unified API.

Prerequisites

Ruby 2.7+ and Rails installed.
In the BundleUp dashboard, complete steps 1 to 3 of the Quickstart:
- a GitHub integration with the identifier github,
- http://localhost:3000/callback registered under Auth → Redirect URIs,
- an API key, and your Client ID from the Auth page.

Step 1: Create a new Rails app

Create a fresh Rails project:

# using Rails CLI
rails new bundleup_rails
cd bundleup_rails

# ensure the app’s database is ready
rails db:create

This scaffolds a Rails app you can run locally.

Step 2: Install the BundleUp Ruby SDK

Add the bundleup-sdk gem to your Gemfile:

# Gemfile
gem 'bundleup-sdk', require: 'bundleup'

Then install dependencies:

bundle install

This makes the BundleUp client available to your Rails app.

Step 3: Configure environment variables

Create a .env file (or use your preferred secrets manager) with:

.env

# server-side only
BUNDLEUP_API_KEY=your_api_key_here

# used for redirect
BUNDLEUP_CLIENT_ID=your_client_id_here
BUNDLEUP_INTEGRATION_ID=github

# Must exactly match a redirect URI registered in your BundleUp dashboard
BUNDLEUP_REDIRECT_URI=http://localhost:3000/callback

Make sure your Rails app loads these variables (for example via dotenv-rails or Rails credentials).

Step 4: Add routes

In config/routes.rb, define the home and callback endpoints:

config/routes.rb

Rails.application.routes.draw do
  root "home#index"
  get "/callback", to: "home#callback"
end

Step 5: Create the authorization link

In app/controllers/home_controller.rb, add:

app/controllers/home_controller.rb

class HomeController < ApplicationController
  def index
    @auth_url = bundleup.auth.build_authorization_url(
      client_id: ENV["BUNDLEUP_CLIENT_ID"],
      integration_id: ENV["BUNDLEUP_INTEGRATION_ID"],
      redirect_uri: ENV["BUNDLEUP_REDIRECT_URI"]
    )
  end

  private

  def bundleup
    @bundleup ||= BundleUp::Client.new(ENV["BUNDLEUP_API_KEY"])
  end
end

Then create a simple view.

app/views/home/index.html.erb

<%= link_to "Connect GitHub", @auth_url %>

This link sends the user to BundleUp’s auth server to authorize the integration.

Step 6: Handle the callback and fetch data

After authorization, BundleUp redirects back to /callback with a one-time code. Your server exchanges it, using your API key, for a connection_id. The code expires after 5 minutes and can only be used once. Add a callback action to HomeController:

app/controllers/home_controller.rb

class HomeController < ApplicationController
  def index
    @auth_url = bundleup.auth.build_authorization_url(
      client_id: ENV["BUNDLEUP_CLIENT_ID"],
      integration_id: ENV["BUNDLEUP_INTEGRATION_ID"],
      redirect_uri: ENV["BUNDLEUP_REDIRECT_URI"]
    )
  end

  def callback
    if params[:error] || params[:code].blank?
      @error = params[:error_description] || "Missing code"
      return
    end

    # Exchange the one-time code for the connection (server-side only)
    connection = bundleup.auth.get_connection_from_code(
      code: params[:code],
      redirect_uri: ENV["BUNDLEUP_REDIRECT_URI"]
    )

    # example: fetch GitHub repos
    @repos = bundleup.unify(connection["connection_id"]).git.repos["data"]
  end

  private

  def bundleup
    @bundleup ||= BundleUp::Client.new(ENV["BUNDLEUP_API_KEY"])
  end
end

redirect_uri must be exactly the same value you used to start the flow. BundleUp rejects the exchange otherwise.

Then create app/views/home/callback.html.erb:

app/views/home/callback.html.erb

<% if @error %>
  <p>Error: <%= @error %></p>
<% else %>
  <h2>Repositories</h2>
  <ul>
    <% @repos.each do |repo| %>
      <li><%= repo["full_name"] %></li>
    <% end %>
  </ul>
<% end %>

Now, after a successful authorization redirect, you exchange the code for a connection_id and use it to fetch a Unified API resource with the Ruby SDK.

Step 7: Run your application

Start the Rails server:

rails server

Visit http://localhost:3000, click Connect GitHub, authorize the app, and then you’ll see data fetched through BundleUp.

Next steps

Store the connection_id against the signed-in user in your database, and reuse it. Don’t send the user through the flow again.
Pass a state value when you build the authorization URL and check it in the callback, to protect against CSRF. See Connecting user accounts.
Pass an external_id (your user ID) so you can find connections by user later.
Call the provider directly through the Proxy when you need something the Unified API doesn’t cover.
See the full Ruby SDK reference.

Get started

Concepts

Authentication

Integrations

Proxy

Unified API

MCP

Webhooks

Operations

Platform

Prerequisites

Step 1: Create a new Rails app

Step 2: Install the BundleUp Ruby SDK

Step 3: Configure environment variables

Step 4: Add routes

Step 5: Create the authorization link

Step 6: Handle the callback and fetch data

Step 7: Run your application

Next steps

​Prerequisites

​Step 1: Create a new Rails app

​Step 2: Install the BundleUp Ruby SDK

​Step 3: Configure environment variables

​Step 4: Add routes

​Step 5: Create the authorization link

​Step 6: Handle the callback and fetch data

​Step 7: Run your application

​Next steps

Prerequisites

Step 1: Create a new Rails app

Step 2: Install the BundleUp Ruby SDK

Step 3: Configure environment variables

Step 4: Add routes

Step 5: Create the authorization link

Step 6: Handle the callback and fetch data

Step 7: Run your application

Next steps