Doorkeeper is an OAuth 2 provider for Rails.
Ruby JavaScript
Pull request Compare This branch is 1110 commits behind doorkeeper-gem:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Doorkeeper - awesome oauth provider for your Rails app.

Build Status Dependency Status

Doorkeeper is a gem that makes it easy to introduce OAuth 2 provider functionality to your application.

The gem is under constant development. It is based in the version 22 of the OAuth specification and it still does not support all OAuth features.

For more information about the supported features, check out the related page in the wiki. For more information about OAuth 2 go to OAuth 2 Specs (Draft).


Put this in your Gemfile:

gem 'doorkeeper', '~> 0.3.0'

Run the installation generator with:

rails generate doorkeeper:install

This will generate the doorkeeper initializer and the OAuth tables migration. Don't forget to run the migration in your application:

rake db:migrate


The installation script will automatically add the Doorkeeper routes into your app, like this:

Rails.application.routes.draw do
  mount Doorkeeper::Engine => "/oauth"
  # your routes

This will mount following routes:

GET       /oauth/authorize
POST      /oauth/authorize
DELETE    /oauth/authorize
POST      /oauth/token
resources /oauth/applications

You need to configure Doorkeeper in order to provide resource_owner model and authentication block initializers/doorkeeper.rb

Doorkeeper.configure do
  resource_owner_authenticator do |routes|
    current_user || redirect_to('/sign_in', :alert => "Needs sign in.") # returns nil if current_user is not logged in

If you use devise, you may want to use warden to authenticate the block:

resource_owner_authenticator do |routes|
  current_user || warden.authenticate!(:scope => :user)

Protecting resources with OAuth (a.k.a your API endpoint)

To protect your API with OAuth, doorkeeper only requires you to call doorkeeper_for helper, specifying the actions you want to protect.

For example, if you have a products controller under api/v1, you can require the OAuth authentication with:

class Api::V1::ProductsController < Api::V1::ApiController
  doorkeeper_for :all                     # Require access token for all actions
  doorkeeper_for :all, :except => :index  # All actions except index
  doorkeeper_for :index, :show            # Only for index and show action

  # your actions

You don't need to setup any before filter, doorkeeper_for will handle that for you.

You can pass if or unless blocks that would specify when doorkeeper has to guard the access.

class Api::V1::ProductsController < Api::V1::ApiController
  doorkeeper_for :all, :if => lambda { request.xhr? }

Access Token Scopes

You can also require the access token to have specific scopes in certain actions:

class Api::V1::ProductsController < Api::V1::ApiController
  doorkeeper_for :index, :show,    :scopes => [:public]
  doorkeeper_for :update, :create, :scopes => [:admin, :write]

For a more detailed explanation about scopes usage, check out the related page in the wiki.

Authenticated resource owner

If you want to return data based on the current resource owner, in other words, the access token owner, you may want to define a method in your controller that returns the resource owner instance:

class Api::V1::CredentialsController < Api::V1::ApiController
  doorkeeper_for :all
  respond_to     :json

  # GET /me.json
  def me
    respond_with current_resource_owner


  # Find the user that owns the access token
  def current_resource_owner
    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token

In this example, we're returning the credentials (me.json) of the access token owner.

Other resources

Live demo

Check out this live demo hosted on heroku. For more demos check out the wiki.

Client applications

After you set up the provider, you may want to create a client application to test the integration. Check out these client examples in our wiki or follow this tutorial here.


Want to contribute and don't know where to start? Check out features we're missing, create example apps, integrate the gem with your app and let us know!

Also, check out our contributing guidelines page.

Supported ruby versions

All supported ruby versions are listed here

Additional information



Thanks to all our awesome contributors!


MIT License. Copyright 2011 Applicake.