Api Guardian

Drop in authorization and authentication suite for Rails APIs.

Build Status Test Coverage Code Climate

**This gem is in alpha stages and is not feature complete. It should not be used in production!**


ApiGuardian includes the following features out of the box:

  • User registration (email/pass)
  • Password reset workflow
  • Roles
  • Permissions
  • Stateless authentication using OAuth2 (via Doorkeeper and Doorkeeper::JWT)
  • Policy enforcement (via Pundit)
  • Serialization to JSON API (via AMS)
  • Two-factor auth
  • External Login (TODO)

What doesn't it include?

  • Stateful session support (Cookies)
  • HTML/CSS/JS or views of any kind.


  • Ruby >= 2.1
  • PostgreSQL >= 9.3 (JSON and uuid-ossp support)

Note: For now, your app must use a PostgreSQL database. This is because ApiGuardian is using UUID primary keys for all records.

Quick Start


Put this in your Gemfile:

# Include ApiGuardian from edge
gem 'api_guardian', git: 'https://github.com/lookitsatravis/api_guardian'
# You must also include the prerelease version of active_model_serializers
gem 'active_model_serializers', git: 'https://github.com/rails-api/active_model_serializers.git'


Run the following command. It will:

  • Add an initializer
  • Mount ApiGuardian in your routes file
  • Copy migration files
  • Add seed data
rails generate api_guardian:install

You will need to follow this with:

rake db:migrate

Take a moment here to review your seed file and make any changes. And then:

rake db:seed


Make all of your API controllers extend ApiGuardian::ApiController and your policies extend ApiGuardian::Policies::ApplicationPolicy. What is a policy, you ask, and why should you care? Well, I'm glad you asked!

See our Documentation for way more information on setup and usage, or take a look at the RDoc formatted docs here:



  • controller actions:
    • Assign permissions to role by name
  • Multi-tenancy
    • Invite users by email to organization
    • Users can belong to multiple organizations?
    • Different roles based on organization? Or permissions?
  • Configuring allowed CORS domains (to better protect insecure clients)
  • omniauth
  • Account lockout (failed login attempts)
  • https://github.com/kickstarter/rack-attack
  • 2FA
    • review support for https://www.authy.com/product/
    • review support for U2F
    • Generate URL for Google Authenticator import
    • Backup codes for when device is unavailable
    • 16 one time use codes
    • Ability to regenerate a new batch of codes
  • Activity/Events (User signed in, User authenticated at...)
  • Sessions/Devices (attach to tokens, but how?)
  • Fix for JWT storage: https://github.com/doorkeeper-gem/doorkeeper/wiki/How-to-fix-PostgreSQL-error-on-index-row-size
  • Cache
  • SSO
  • Review Auth0 feature set
  • Documentation
    • Microservice usage
    • Request logging
  • Remove dependency on PostgreSQL
  • Ability to swap AMS adapter
    • Error rendering needs to match this setting
  • Toggle custom logger off
  • Add test for custom logger
  • Soft deleting and cascade deleting
  • A role can't be destroyed if users still belong to it
  • Remove dependencies on gems
    • What could be moved to core?
    • pundit
    • doorkeeper
    • otp
    • acts_as_tenant
    • Phony
    • What could feasibly be added as an "addon" package
    • Paranoia
    • zxcvbn-js
    • twilio-ruby

Getting Help

If you find a bug, please report an Issue.

If you have a question, please post to Stack Overflow.





ApiGuardian is copyright © 2016 Travis Vignon. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.