Create a Ruby on Rails 5.2 API with Auth0 Authentication

    Try Storyblok

    Storyblok is the first headless CMS that works for developers & marketers alike.

    In this tutorial, we will walk you through the setup of a Ruby on Rails 5.2 API Application combined with Auth0. After this, you will have an API with private and public routes than you can use for our tutorial on “How to add Auth0 to Vue.js in 7 Steps” which allows you to make authenticated calls on this API. During this tutorial, you will learn how to set up a custom Concern, a JSON Web Token verification, a Private and a Public route that returns JSON.


    • Ruby installed -> 2.5.0p0
    • Rails installed -> 5.2.0
    • Auth0 Account

    Auth0 - Rails

    What is Rails

    Rails is a web application development framework written in the Ruby programming language. It is designed to make programming web applications easier by making assumptions about what every developer needs to get started. It allows you to write less code while accomplishing more than many other languages and frameworks. Experienced Rails developers also report that it makes web application development more fun. You can read more on their website.

    What is Auth0

    Auth0 provides authentication and authorization as a service. They are here to give developers and companies the building blocks they need in order to secure their applications, without having to become security experts. You can connect any application (written in any language or on any stack) to Auth0 and define the identity providers you want to use (how you want your users to log in). Based on your app’s technology, choose one of our SDKs (or call our API) and hook it up to your app. Now each time a user tries to authenticate, Auth0 will verify their identity and send the required information back to your app. If you want to learn more about what Auth0 check out their getting started overview.

    Auth0 Setup

    Before we start our dig into Rails 5.2 and the setup, we will access the Auth0 application to add an API so we can configure our application accordingly. To do so access the API Menu in the Management App (

    Auth0 API Management Dashboard

    Press the orange + Create API button on the top right corner to open the creation modal.

    Auth0 API Creation button

    Enter your information as I did in the screenshot below. In audience you do ** not** have to add http://localhost:4000 - note: this identifier (which do not need to be an URL) cannot be modified, but you can, of course, create a new API if needed.

    Auth0 create API modal

    Well done! You’re ready to start your authentication journey. Sadly the Quickstart of Auth0s API section does not include a Rails Copy&Past example right away but you can find all you need later in this tutorial. The big benefit of the already available Quickstarts is that you have all the information you need to configure in one place (the node.js example). All those information can also be found in the Settings Tab.

    Auth0 quickstart

    Environment Setup

    This tutorial will use a freshly created Rails project. You can also add Auth0 to an existing project using the same/similar approach as presented here.

    ## PostgreSQL
    rails new my_api --api --database=postgresql
    ## SQLite3
    rails new my_api --api

    If you already have your own project have a look at their guide on how to change an existing application.

    Install dependencies

    We will use the jwt gem for validation within our own JsonWebToken class and a custom Concern to mark endpoints which should require authentication through an incoming AccessToken from your client application. You can check our tutorial for a Vue.js Client that already handles the authentication process.

    # add to your Gemfile
    gem 'jwt'
    # execute on the command line
    bundle install

    Creating our JsonWebToken Class

    The code we’re going to use from the official Auth0 Ruby on Rails getting started which I highly recommend you to open as well since it ships with your project configuration out of the box.

    Before we will create a JsonWebToken class, which we will use to verify the incoming AccessToken of the Request Authorization Header, we have to make some adjustments: Rails 5.2 has some changes that will require you to either change your understanding of the /app and /lib folder or to add one line to allow the “old” behavior. Since with 5.2, you will not be able to directly use the /lib directory for non-domain specific classes. There are two ways to approach this:

    # 1: Move /lib in to /app/lib
    # As recommended by a member:
    # 2: Add a line to your config/environment.rb
    Dir[Rails.root.join('lib/**/*.rb')].each { |f| require f }
    # As recommended by another contributor:

    I will go ahead and follow the /app/lib approach, for now, feel free to also use the other. Thanks to an awesome group of contributors we can use a pure ruby implementation of the RFC 7519 OAuth JSON Web Token (JWT) standard as shown below.

    # app/lib/json_web_token.rb
    # frozen_string_literal: true
    require 'net/http'
    require 'uri'
    class JsonWebToken
      def self.verify(token)
        JWT.decode(token, nil,
            true, # Verify the signature of this token
            algorithm: 'RS256',                          # RS256 or HS256
            iss: 'https://YOUR_AUTH0_TENANT_DOMAIN/',    # something like
            verify_iss: true,
            aud: Rails.application.secrets.auth0_api_audience,
            verify_aud: true) do |header|
      def self.jwks_hash
        jwks_raw = Net::HTTP.get URI("https://YOUR_AUTH0_TENANT_DOMAIN/.well-known/jwks.json")
        jwks_keys = Array(JSON.parse(jwks_raw)['keys'])
          .map do |k|

    Adding your Auth0 API Audience

    With Rails 5.2 is out with a brand new credentials API that will replace the current config/secrets.yml. The idea behind the change is mainly to remove some of the confusion introduced by the combinations of config/secrets.yml, config/secrets.yml.enc and SECRET_BASE_KEY used in earlier versions of Rails, and attempt to unify everything using a more straightforward approach. You can read more about this Change in their Pull Request on Github.

    Your Rails application should already have those two files available instead:

    • config/credentials.yml.enc
    • config/master.key

    As it’s extension .enc suggests, this file is going to be encrypted using the master.key - nobody is able to read what’s inside - unless they have the proper master key to decrypt it. So you can add the config/credentials.yml.enc to your version control. On the other hand the config/master.key should not be in your version control eg. git repository. New Rails 5.2 apps already have it in the .gitignore to make sure you won’t commit it. Everybody that has that config/master.key will be able to decrypt your credentials.yml.enc file and therefore has access to your credentials.

    Editing your encrypted Rails credentials file

    Rails 5.2 comes with a way to edit the config/credentials.yml.enc so you won’t have to decrypt and encrypt your file each time on your own. For this to work with your favorite editor you will have to have $EDITOR defined, to do so in one command you can use the list below, let me know in the comments or on Twitter which editor you use and how you edited it.

    # Visual Studio Code
    EDITOR="code --wait" bin/rails credentials:edit
    # Visual Studio Code Insiders
    EDITOR="code-insiders --wait" bin/rails credentials:edit
    # Atom 
    EDITOR="atom --wait" bin/rails credentials:edit
    # Sublime Text 3
    EDITOR="subl --wait" bin/rails credentials:edit
    # Vim
    EDITOR=vim bin/rails credentials:edit

    You should now be able to see a demo .yml structure where we can now add our own configuration/credentials. We will go ahead and add the namespace auth0 and attribute api_audience with your audience as shown below, you can also introduce staging namespaces as you would in a normal .yml file. It is a good idea to have the credentials for environments protected by different master keys so that all of your development machines don’t have access to the production credentials, however, if you want to use one key to encrypt them and use namespaces you can find an example right here as well:

    # aws:
    #   access_key_id: 123
    #   secret_access_key: 345
    # without staging namespaces
      api_audience: 'my_audience'
    # With staging namespaces
    # development:
    #   auth0:
    #     api_audience: 'my_audience'
    # test:
    #   auth0:
    #     api_audience: 'my_audience'
    # Used as the base secret for all MessageVerifiers in Rails, including the one protecting cookies.
    secret_key_base: XXXXXXXXXXXXXXXXXX

    The audience you’re using here must be the same as you added in your clients’ setup. You can read more about the audience and what an audience actually is in the Auth0 docs. If you have an issue with audiences check the auth0 logs and if you have an API with that audience in place.

    Updating the JsonWebToken file

    You may notice the line Rails.application.secrets.auth0_api_audience which still uses the old secrets and that would actually still work but since we don’t even have it (if you have created a new project as we did and not upgraded) we exchange that with our credentials: Rails.application.credentials[:auth0][:api_audience].

    # app/lib/json_web_token.rb
      def self.verify(token)
        JWT.decode(token, nil,
            true, # Verify the signature of this token
            algorithm: 'RS256',                          
            iss: 'https://YOUR_AUTH0_TENANT_DOMAIN/',
            verify_iss: true,
            # aud: Rails.application.secrets.auth0_api_audience, ## <----- Notice me!
            # aud: Rails.application.credentials[Rails.env.to_sym][:auth0][:api_audience] ## With staging namespace
            aud: Rails.application.credentials[:auth0][:api_audience], ## No staging namespace
            verify_aud: true) do |header|

    Define your Secured concern

    Next we will create a custom Concern called Secured which checks for the AccessToken in the Authorization request header. If the token is present, it should be passed to JsonWebToken.verify. If you experience an issue at this point that JsonWebToken is not defined or can not be loaded, make sure to have the /lib folder moved to app/lib or add Dir[Rails.root.join('lib/**/*.rb')].each { |f| require f } to your config/environment.rb

    # app/controllers/concerns/secured.rb
    # frozen_string_literal: true
    module Secured
      extend ActiveSupport::Concern
      included do
        before_action :authenticate_request!
      def authenticate_request!
      rescue JWT::VerificationError, JWT::DecodeError
        render json: { errors: ['Not Authenticated'] }, status: :unauthorized
      def http_token
        if request.headers['Authorization'].present?
          request.headers['Authorization'].split(' ').last
      def auth_token

    Public and Private route

    To test our application we will add two new controllers (a public and private) to our application.

    # Generate the Public Controller with a hello route
    bin/rails generate controller Public hello
    class PublicController < ApplicationController
      def hello
        render json: { message: 'Hello from a public endpoint! You don\'t need to be authenticated to see this.' }

    The public controller should now already be accessible via /public/hello after you’ve started your server rails s -p {your_port}.

    # Generate the Private Controller with a hello route
    bin/rails generate controller Private hello
    class PrivateController < ApplicationController
      def hello
        render json: { message: 'Hello from a private endpoint! You need to be authenticated to see this.' }

    The private controller should now also be accessible via /private/hello, to tell Rails that this controller should use our Secured Concern all we have to add is one line:

    class PrivateController < ApplicationController
      include Secured ## <- our Secured Concern
      def hello
        render json: { message: 'Hello from a private endpoint! You need to be authenticated to see this.' }

    If you now access the /private/hello route you will receive an error that should look like:

      "errors": [
        "Not Authenticated"

    Nice! We now have a check for the Authorization Header and not let our request through! Well done!

    Test/Accessing your Authenticated endpoint

    To test your authenticated endpoints you can navigate to the Auth0 Test Panel of your API in the Auth0 app, where you can find, not only a CURL that is preconfigured and looks like the one below, but also many more code examples in various technologies. You can also use our Vue.js example by exchanging the audience with the one of your newly created API in Auth0. The Test suite can be found at the last Tab in the API Configuration in the Auth0 Dashboard.

    Auth0 Test Tab

    1. Get your JWT from Auth0

    The basic request your client can perform by posting to the Auth0 /oauth/token endpoint should look like:

    curl --request POST \
      --url https://YOUR_AUTH0_URL/oauth/token \
      --header 'content-type: application/json' \
      --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials"}'

    The response you expect from that endpoint should have the following body:

      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciO...h61Ad5VIsCM8m9AD3sHda83Q",
      "token_type": "Bearer"

    2. Use that token against your API

    In your client application, we now send that token as Authorization header to our API

    curl --request GET \
      --url http://path_to_your_api/ \
      --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciO...h61Ad5VIsCM8m9AD3sHda83Q'

    and expect the following result:

      "message":"Hello from a private endpoint! You need to be authenticated to see this."

    Wrapping it up

    Adding Auth0 to a Rails application is unbelievable easy by following the official guide. However, since it currently does not cover the differences in Rails 5.2 I felt the need to update and document that part for you so you won’t fall into the above changes. The benefits from not writing your own Authentication in every application and instead use an Identify Service like Auth0 is such a boost for your productivity and increase in security that I would highly recommend you to check it out yourself.

    With the change in Rails 5.2 that enables you to actually use encrypted credentials out of the box is great, even tho some will miss the old, now deprecated, secrets.yml. Even tho you can still use it, it is now no longer the recommended way so keep that in mind while upgrading. The issue with the lib folder was interesting to read on Github and took me longer to find the “best” way as I wished for. As many of you requested this is now the first API part of the Auth0 tutorials we created at Storyblok since we do use Ruby and Auth0 ourselves. Feel free to leave your comments down below or write your tweet your feedback on Twitter.