Ruby API

Community maintained

Sample Project

Download a sample project specific to this tutorial configured with your Auth0 API Keys.

System Requirements
  • Ruby 2.3.0
Show requirements

This tutorial shows you how to use the authorization features in the OAuth 2.0 framework to limit access to your or third-party applications. For more information, read the API authorization documentation.

Create a Resource Server (API)

In the APIs section of the Auth0 dashboard, click Create API. Provide a name and an identifier for your API. You will use the identifier as an audience later, when you are configuring the access token verification. For Signing Algorithm, select RS256.

Create API

Add API Authorization

To restrict access to the resources served by your API, check the incoming requests for valid authorization information. The authorization information is stored in the access token created for the user and needs to be sent in the Authorization header. To see if the token is valid, check it against the JSON Web Key Set (JWKS) for your Auth0 account. To learn more about validating access tokens, read the Verify Access Tokens tutorial.

This sample demonstrates how to check for a JWT in the Authorization header of an incoming HTTP request and verify that it is valid. The validity check is done using the jwt Gem within a custom JsonWebToken class. An authenticate! method is used to mark endpoints which require authentication through an incoming access_token. If the token is valid, the resources which are served by the endpoint can be released, otherwise a 401 Authorization error will be returned.

Install the Dependencies

Install the jwt Gem.

gem `jwt`
bundle install

Create a JsonWebToken Class

Create a class called JsonWebToken which decodes and verifies the incoming access_token token from the Authorization header of the request. The public key for your Auth0 tenant can be fetched to verify the token.

# lib/jwt/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',
               iss: 'https://YOUR_AUTH0_DOMAIN/'
               verify_iss: true,
               # auth0_api_audience is the identifier for the API set up in the Auth0 dashboard
               aud: auth0_api_audience
               verify_aud: true) do |header|

  def self.jwks_hash
    jwks_raw = Net::HTTP.get URI("https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json")
    jwks_keys = Array(JSON.parse(jwks_raw)['keys'])
      .map do |k|


Define an authenticate! method

Create an authenticate! method to run before each endpoint which looks for the access_token in the Authorization header of an incoming request. If the token is present, it should be passed to JsonWebToken.verify.

# lib/server_rs256.rb

def authenticate!
  # Extract <token> from the 'Bearer <token>' value of the Authorization header
  supplied_token = String(request.env['HTTP_AUTHORIZATION']).slice(7..-1)

  @auth_payload, @auth_header = JsonWebToken.verify(supplied_token)

rescue JWT::DecodeError => e
  halt 401, json(error: e.class, message: e.message)

before do

get '/restricted_resource' do
  json( message: 'Access Granted', allowed_scopes: String(@auth_payload['scope']).split(' ') )

Configure Scopes

The JsonWebToken.verify method above verifies that the access_token included in the request is valid; however, it doesn't yet include any mechanism for checking that the token has the sufficient scope to access the requested resources.

Scopes provide a way for you to define which resources should be accessible by the user holding a given access_token. For example, you might choose to permit read access to a messages resource if a user has a manager access level, or write access to that resource if they are an administrator.

To configure scopes in your Auth0 dashboard, navigate to your API and choose the Scopes tab. In this area you can apply any scopes you wish, including one called read:messages, which will be used in this example.

Protect Individual Endpoints

To look for a particular scope in an access_token, provide an array of required scopes and check if they are present in the payload of the token.

In this example the SCOPES array for the given key /restricted_resource is intersected with the scopes contained in the payload of the access_token to determine if it contains one or more items from the array.

# lib/server_rs256.rb

  '/restricted_resource' => ['read:messages'],
  '/another_resource'    => ['some:scope', 'some:other_scope']

def authenticate!
  # Extract <token> from the 'Bearer <token>' value of the Authorization header
  supplied_token = String(request.env['HTTP_AUTHORIZATION']).slice(7..-1)

  @auth_payload, @auth_header = JsonWebToken.verify(supplied_token)

  halt 403, json(error: 'Forbidden', message: 'Insufficient scope') unless scope_included

rescue JWT::DecodeError => e
  halt 401, json(error: e.class, message: e.message)

def scope_included
  # The intersection of the scopes included in the given JWT and the ones in the SCOPES hash needed to access
  # the PATH_INFO, should contain at least one element
  (String(@auth_payload['scope']).split(' ') & (SCOPES[request.env['PATH_INFO']])).any?

With this configuration in place, only access_tokens which have a scope of read:messages will be allowed to access this endpoint.

Make a Call to Your API

To make calls to your API, you need an access token. You can get an access token for testing purposes from the test lab in your API settings.

Obtain a JWT

Provide the access token as an Authorization header in your requests.

curl --request GET \
  --url \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
var client = new RestClient("");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
IRestResponse response = client.Execute(request);
package main

import (

func main() {

	url := ""

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)


HttpResponse<String> response = Unirest.get("")
  .header("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "",
  "method": "GET",
  "headers": {
    "authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"

$.ajax(settings).done(function (response) {
var request = require("request");

var options = { method: 'GET',
  url: '',
  headers: { authorization: 'Bearer YOUR_ACCESS_TOKEN_HERE' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@""]
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
[dataTask resume];
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "",
    "authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

$response = curl_exec($curl);
$err = curl_error($curl);


if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
import http.client

conn = http.client.HTTPConnection("")

headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN_HERE" }

conn.request("GET", "/api_path", headers=headers)

res = conn.getresponse()
data =

require 'uri'
require 'net/http'

url = URI("")

http =, url.port)

request =
request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN_HERE'

response = http.request(request)
puts response.read_body
import Foundation

let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"]

var request = NSMutableURLRequest(URL: NSURL(string: "")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "GET"
request.allHTTPHeaderFields = headers

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
  } else {
    let httpResponse = response as? NSHTTPURLResponse


Use Auth0 for FREECreate free Account