A Ruby gem that allows Oauth2 protection with Doorkeeper for Grape Api's
Alternatives To Wine_bouncer
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Grape9,6966,7172039 days ago64December 30, 2021239mitRuby
An opinionated framework for creating REST-like APIs in Ruby.
Doorkeeper5,1184,009402 days ago109September 08, 202223mitRuby
Doorkeeper is an OAuth 2 provider for Ruby on Rails / Grape.
Rocket_pants9847674 years ago30September 22, 201537mitRuby
API building tools on top of ActionController. Also, an awesome name.
Api Pagination65332914a year ago32October 26, 202123mitRuby
:page_facing_up: Link header pagination for Rails and Grape APIs.
Okcomputer2906952 years ago67February 04, 20214mitRuby
Provides a health-check endpoint to your Ruby on Rails apps.
Grape Swagger Rails242
21 hours ago25mitJavaScript
Swagger UI as Rails Engine for grape-swagger gem.
Scout_apm_ruby16712674 months ago288December 09, 202228otherRuby
ScoutAPM Ruby Agent. Supports Rails, Sinatra, Grape, Rack, and many other frameworks
Grape On Rails166
2 days agoRuby
Sample Grape API mounted on Rails.
Grape_logging14016212 years ago17August 26, 202014mitRuby
Request logging for Grape!
25 months ago3November 09, 2018mitRuby
Easily Translate Enums in Rails
Alternatives To Wine_bouncer
Select To Compare

Alternative Project Comparisons


Build Status Code Climate Gem Version Documentation

Protect your precious Grape API with Doorkeeper. WineBouncer uses minimal modification, to make the magic happen.

Table of Contents


  • Ruby > 2.1
  • Doorkeeper > 1.4.0 and < 5
  • Grape > 0.10 and < 1.2

Please submit pull requests and Travis env bumps for newer dependency versions.


Add this line to your application's Gemfile:

gem 'wine_bouncer', '~> 1.0.4'

And then execute:



When upgrading from a previous version, see UPGRADING. You might also be interested at the CHANGELOG.


WineBouncer is a custom Grape Middleware used for Authentication and Authorization. We assume you have a Grape API mounted in your Rails application together with Doorkeeper.

To get started with WineBouncer, run the configuration initializer:

$ rails g wine_bouncer:initializer

This creates a rails initializer in your Rails app at config/initializers/wine_bouncer.rb with the following configuration:

WineBouncer.configure do |config|
  config.auth_strategy = :default

  config.define_resource_owner do
    User.find(doorkeeper_access_token.resource_owner_id) if doorkeeper_access_token

Then register WineBouncer as Grape middleware in your Grape API.

class Api < Grape::API
   default_format :json
   format :json
   use ::WineBouncer::OAuth2
   mount YourAwesomeApi

Easy DSL

WineBouncer comes with an easy DSL and relies on Grape's DSL extentions to define if an endpoint method should be protected. You can protect an endpoint by calling oauth2 method with optional scopes in front of the endpoint definition.

 class MyAwesomeAPI < Grape::API
    desc 'protected method with required public scope'
    oauth2 'public'
    get '/protected' do
       { hello: 'world' }

    oauth2 'public'
    get '/with_no_description' do
       { hello: 'undescribed world' }

    desc 'Unprotected method'
    get '/unprotected' do
      { hello: 'unprotected world' }

    desc 'This method needs the public or private scope.'
    oauth2 'public', 'write'
    get '/method' do
      { hello: 'public or private user.' }

    desc 'This method uses Doorkeepers default scopes.',
    get '/protected_with_default_scope' do
       { hello: 'protected unscoped world' }

 class Api < Grape::API
    default_format :json
    format :json
    use ::WineBouncer::OAuth2
    mount MyAwesomeAPI

Authentication strategies

Behaviour of the authentication can be customized by selecting an authentication strategy. The following authentication strategies are provided in the gem.


The default strategy only authenticates endpoints which are annotated by the oauth2 method. Un-annotated endpoints still can be accessed without authentication.


WineBouncer comes with a strategy that can be perfectly used with grape-swagger with a syntax compliant with the swagger spec. This might be one of the simplest methods to protect your API and serve it with documentation. You can use swagger-ui to view your documentation.

To get started ensure you also have included the grape-swagger gem in your gemfile.

Run bundle to install the missing gems.

Create a rails initializer in your Rails app at config/initializers/wine_bouncer.rb with the following configuration.

WineBouncer.configure do |config|
    config.auth_strategy = :swagger

    config.define_resource_owner do
            User.find(doorkeeper_access_token.resource_owner_id) if doorkeeper_access_token

Then you can start protecting your API like the example below.

desc 'This method needs the public or private scope.',
  success: Api::Entities::Response,
  failure: [
      [401, 'Unauthorized', Api::Entities::Error],
      [403, 'Forbidden', Api::Entities::Error]
  notes: <<-NOTE
  Marked down notes!
oauth2 'public', 'write'
get '/method' do
  { hello: 'public or private user.' }

The Swagger strategy uses scopes and injects them in the authorizations description for external application to be read.


The protected strategy is very similar to the default strategy except any public endpoint must explicitly set. To make an end point public, use oauth2 false. If the authorization method is not set, the end point is assumed to be protected with Doorkeeper's default scopes (which is the same as oauth2 nil.) To protect your endpoint with other scopes append the following method oauth2 'first scope', 'second scope'.

Token information

WineBouncer comes with free extras! Methods for resource_owner and doorkeeper_access_token get included in your endpoints. You can use them to get the current resource owner, and the access_token object of doorkeeper.

Disable WineBouncer

If you want to disable WineBouncer conditionally - e.g. in specs - you can add a block to the WineBouncer configuration. When this block evaluates to true, any request will be unprotected. For example:

WineBouncer.configure do |config|
  config.disable do

The block is newly evaluated for every request, so you could in principle have something like:

config.disable do
  [true, false].sample

You probably shouldn't, though.

Exceptions and Exception handling

This gem raises the following exceptions which can be handled in your Grape API, see Grape documentation.

  • WineBouncer::Errors::OAuthUnauthorizedError when the request is unauthorized.
  • WineBouncer::Errors::OAuthForbiddenError when the token is found but scopes do not match.

Detailed doorkeeper error response can be found in the error's response attribute. You could use it to compose the actual HTTP response to API users.

Example/Template Application

A full working sample app (or starter template) can be found at grape-doorkeeper on github. It has one click deploy to Heroku and a live example.


Since we want the gem tested against several rails versions we use the same way to prepare our development environment as Doorkeeper.

To install the development environment for rails 4.2.6, you can also specify a different rails version to test against.

rails=4.2.6 bundle install

To run the specs.

rails=4.2.6 bundle exec rake


For contributing to the gem see CONTRIBUTING.

Popular Grape Projects
Popular Ruby On Rails Projects
Popular Frameworks Categories

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Ruby On Rails