Enable Role-Based Access Control for APIs

You can enable role-based access control (RBAC) using the Auth0 Dashboard or the Management API. This enables the API Authorization Core feature set.

Any configured rules run after the RBAC-based authorization decisions are made, so they may override the default behavior.

Dashboard

  1. Go to Dashboard > Applications > APIs and click the name of the API to view.

    Dashboard Applications APIs List

  2. Scroll to RBAC Settings and enable the Enable RBAC toggle.

    Auth0 Dashboard API Settings RBAC toggle

  3. To include all permissions assigned to the user in the permissions claim of the access token, enable the Add Permissions in the Access Token toggle, and click Save. Including permissions in the access token allows you to make minimal calls to retrieve permissions, but increases token size. As long as RBAC is enabled, the scope claim of the access token includes an intersection of the requested permissions and the permissions assigned to the user, regardless of whether permissions are also included in the access token. When RBAC is disabled, the default behavior is observed; an application can request any permission defined for the API, and the scope claim will include all requested permissions.

Management API

Make a PATCH call to the Update Resource Server endpoint. Be sure to replace API_ID, MGMT_API_ACCESS_TOKEN, PERMISSION_NAME, and PERMISSION_DESC placeholder values with your API ID, Management API access token, permission name(s), and permission description(s), respectively.


curl --request PATCH \
  --url 'https://YOUR_DOMAIN/api/v2/resource-servers/API_ID' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{ "enforce_policies": "true", "token_dialect": "TOKEN_DIALECT" }'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/resource-servers/API_ID");
var request = new RestRequest(Method.PATCH);
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
request.AddHeader("cache-control", "no-cache");
request.AddParameter("application/json", "{ \"enforce_policies\": \"true\", \"token_dialect\": \"TOKEN_DIALECT\" }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/api/v2/resource-servers/API_ID"

	payload := strings.NewReader("{ \"enforce_policies\": \"true\", \"token_dialect\": \"TOKEN_DIALECT\" }")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("content-type", "application/json")
	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
	req.Header.Add("cache-control", "no-cache")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.patch("https://YOUR_DOMAIN/api/v2/resource-servers/API_ID")
  .header("content-type", "application/json")
  .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
  .header("cache-control", "no-cache")
  .body("{ \"enforce_policies\": \"true\", \"token_dialect\": \"TOKEN_DIALECT\" }")
  .asString();
var axios = require("axios").default;

var options = {
  method: 'PATCH',
  url: 'https://YOUR_DOMAIN/api/v2/resource-servers/API_ID',
  headers: {
    'content-type': 'application/json',
    authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
    'cache-control': 'no-cache'
  },
  data: {enforce_policies: 'true', token_dialect: 'TOKEN_DIALECT'}
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"content-type": @"application/json",
                           @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                           @"cache-control": @"no-cache" };
NSDictionary *parameters = @{ @"enforce_policies": @"true",
                              @"token_dialect": @"TOKEN_DIALECT" };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/api/v2/resource-servers/API_ID"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"PATCH"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

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, [
  CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/resource-servers/API_ID",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => "{ \"enforce_policies\": \"true\", \"token_dialect\": \"TOKEN_DIALECT\" }",
  CURLOPT_HTTPHEADER => [
    "authorization: Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control: no-cache",
    "content-type: application/json"
  ],
]);

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

curl_close($curl);

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

conn = http.client.HTTPSConnection("")

payload = "{ \"enforce_policies\": \"true\", \"token_dialect\": \"TOKEN_DIALECT\" }"

headers = {
    'content-type': "application/json",
    'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
    'cache-control': "no-cache"
    }

conn.request("PATCH", "/YOUR_DOMAIN/api/v2/resource-servers/API_ID", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://YOUR_DOMAIN/api/v2/resource-servers/API_ID")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Patch.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
request["cache-control"] = 'no-cache'
request.body = "{ \"enforce_policies\": \"true\", \"token_dialect\": \"TOKEN_DIALECT\" }"

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

let headers = [
  "content-type": "application/json",
  "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
  "cache-control": "no-cache"
]
let parameters = [
  "enforce_policies": "true",
  "token_dialect": "TOKEN_DIALECT"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/api/v2/resource-servers/API_ID")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Value Description
API_ID Τhe ID of the API for which you want to enable RBAC.
MGMT_API_ACCESS_TOKEN Access Token for the Management API with the scope update:resource_servers.
TOKEN_DIALECT Dialect of the access token for the specified API.

Token dialect options

Available options include:

Value Description
access_token In the scope claim of the access token, includes an intersection of the requested permissions and the permissions assigned to the user. No permissions claim is passed.
access_token_authz In the scope claim of the access token, includes an intersection of the requested permissions and the permissions assigned to the user. In the permissions claim of the access token, includes all permissions assigned to the user. Allows you to make minimal calls to retrieve permissions, but increases token size.

When RBAC is disabled, default behavior is observed; an application can request any permission defined for the API, and the scope claim will include all requested permissions.

Learn more