Creating and Getting All Roles

Learn how to create a role with specific permissions and get all existing roles using Auth0 API.

We'll cover the following

The Auth0 roles endpoint is for managing user roles in an application. Roles can be used to assign certain permissions or access levels to users, such as an administrator or read-only access. In this lesson, we'll see how to create a role or get a list of our roles using an API call. We'll use the https://{{DOMAIN}}/api/v2/roles endpoint to achieve these tasks. Creating a role is a POST request, while the other is a GET request.

Press + to interact
Creating a role and getting all roles endpoints
Creating a role and getting all roles endpoints

Creating a role

Roles can be used to define permissions and access levels for users within an application and help streamline user management by grouping users with similar permissions together. The roles endpoint is used for this call, requiring our access token to create roles scope.

Request parameters

To invoke this endpoint, we will use a POST request. Therefore, we have a list of parameters that can be passed as body parameters. Let's have a look at the parameters in the table below:

Parameter Name

Type

Category

Description

name

String

Required

Defines the name of the role.

description

String

Optional

Defines the description of the role.

The following code creates a role, and retrieves its role ID. Please click the “Save” button to use that ID in the upcoming lessons. Click the “Run” button to create a role in the code widget below:

Press + to interact
// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/roles');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const bodyParameters = JSON.stringify({
  "name": "Admin-Test",
  "description": "This is a sample description for the Admin role"
});
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
async function createRole() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
createRole();

Let's look at the highlighted lines from the code shown above:

  • Line 4: We define the endpoint URL to create a role.

  • Lines 6–9: We define the headerParameters object, which tells the API call about the type of data we are sending and the access token.

  • Lines 11–14: We define the bodyParameters object.

    • Line 12: We define the name of our role.

    • Line 13: We define the description of our role.

  • Lines 16–20: We define the options object that is used to pass the data required to make an API call.

  • Line 24: We make a POST request using the fetch function.

  • Line 31: We invoke the createRole function.

Response fields

The successful execution of the above code creates a new role and returns its details.

Name

Description

id

Contains the ID of the role.

name

Contains the role's name.

description

Contains the description of the role.

Getting all roles

We can use the roles endpoint to retrieve the list of all the roles created. In this section, we'll see how we can retrieve all the created roles and which parameters can be used to filter the results.

Request parameters

To utilize this endpoint and obtain a list of all available roles, a GET HTTP requests should be sent to the specified endpoint. We can also filter the results by using certain parameters.

Parameter Name

Type

Category

Description

per_page

Integer

Optional

Defines the per-page results that will reflect in the response.

page

Integer

Optional

Defines the page indexes of the results that will reflect in the response.

include_totals

Boolean

Optional

Confirms whether the filtered summary should be included in the response or not.

name_filter

String

Optional

Filters the role with the help of the role name (case sensitive).

The following code retrieves all the roles that we have. Click the “Run” button to extract all roles in the code widget below.

Press + to interact
// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/roles');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const options = {
  method: 'GET',
  headers: headerParameters,
};
async function getAllRoles() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getAllRoles();

Let's look at the highlighted lines from the code shown above:

  • Line 4: We define the endpoint URL to filter all the roles.

  • Line 18: We make a GET request using the fetch function.

  • Line 25: We invoke the getAllRoles function.

Response fields

The successful execution of the above code will list all the roles and return metadata of the roles. Some of the important response fields are as follows.

Name

Description

id

Contains the role ID.

name

Contains the role name.

description

Contains the role description.