Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bundleup.io/llms.txt

Use this file to discover all available pages before exploring further.

Get started with BundleUp in a Rails application. This guide walks you through creating an authorization flow to connect a third-party service (GitHub in this example) and then uses that connection to fetch API data via BundleUp’s unified API. By the end of this guide, you’ll:
  • Redirect a user through an OAuth-style authorization flow
  • Receive a connection_id
  • Use that connection_id server-side with the Ruby SDK to fetch data

​
Prerequisites

Before you begin, make sure you have:
  • A BundleUp account
  • A BundleUp API key (server-side)
  • Your BundleUp Client ID (used for authorization redirects)
  • An Integration ID for the service you want to connect (for example, github)
  • Ruby 2.7+ and Rails installed
You can find your API key, Client ID, and Integration IDs in the BundleUp dashboard.

​
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'
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
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
In app/controllers/home_controller.rb, add:
app/controllers/home_controller.rb
class HomeController < ApplicationController
  def index
    client_id = ENV["BUNDLEUP_CLIENT_ID"]
    integration_id = ENV["BUNDLEUP_INTEGRATION_ID"]
    redirect_uri = ENV["BUNDLEUP_REDIRECT_URI"]

    @auth_url = [
      "https://auth.bundleup.io/authorize?",
      "client_id=#{client_id}",
      "integration_id=#{integration_id}",
      "redirect_uri=#{redirect_uri}"
    ].join("&")
  end

  def callback
    @error = params[:error]
    @error_description = params[:error_description]
    @connection_id = params[:connection_id]
  end
end
Then create simple views.
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

Update callback action in HomeController:
app/controllers/home_controller.rb
require "bundleup-sdk"

class HomeController < ApplicationController
  def callback
    if params[:error]
      @error = params[:error_description]
      return
    end

    connection_id = params[:connection_id]
    client = BundleUp::Client.new(api_key: ENV["BUNDLEUP_API_KEY"])

    # example: fetch GitHub repos
    @repos = client.unify(connection_id).git.repos.data
  end
end
Then update 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 use the connection_id to fetch a unified API resource using 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.

​
What’s next?

  • Persist connection_id to your database for later use
  • Add authenticated views that use the Ruby SDK to fetch user data
  • Support additional integrations with no auth changes