Creating and Getting Client Grant

Learn how to create and get a client grant using Auth0 API.

We'll cover the following

In Auth0, a client grant is a means of granting a specific client application access to a particular set of API resources. This is particularly useful when the client application requires access to the API on behalf of the user. We can use the https://{{DOMAIN}}/api/v2/client-grants endpoint to create and retrieve client grants for a client application. To create a client grant, we need to make a POST request, whereas to retrieve a list of client grants for our client, we need to make a GET request.

Press + to interact
Creating a client grant and get the client grant endpoints
Creating a client grant and get the client grant endpoints

Creating a client grant

A client grant is a way to give a client application access to a specific set of resources or APIs without requiring a user authentication. This can be useful when we have a trusted client application that needs access to specific resources or APIs and when we don’t want to require users to authenticate every time the application needs to access those resources. In this section, we’ill understand how a client grant can be created for a client.

Request parameters

Since this is a POST request, we have a list of parameters we pass as body parameters. Let's have a look at the table below:

Parameter Name

Type

Category

Description

client_id

String

Required

Defines the unique identification of the client.

audience

String

Required

Defines the API Identifier as a client-grant audience.

scope

Array

Required

Defines the client grant scopes.

The following code creates a client grant and returns its client grant ID. Don't forget to click the “Save” button to use that ID in the upcoming widgets throughout the course.

Press + to interact
// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/client-grants');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const bodyParameters = JSON.stringify({
  "client_id": "{{NEW_CLIENT_ID}}",
  "audience": "{{API_IDENTIFIER}}",
  "scope": [
    "update:client_grants"
  ]
});
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
async function createClientGrant() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
createClientGrant();

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

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

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

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

    • Line 12: We specify the client_id at which we want to create a client grant.

    • Line 13: We define the audience parameter in which we pass the API Identifier.

    • Lines 14–16: We define the scope parameter in which we only define the update:client_grants scope for the client. This will give access to this specific client to only update the client grant.

  • Lines 19–23: We define the options object, used to pass data required to make an API call.

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

  • Line 34: We invoke the createClientGrant function.

Response fields

The successful execution of the above code creates a client grant and returns the following details.

Name

Description

id

Contains the client grant ID.

client_id

Contains the unique identifier of the client.

audience

Contains the API identifier for the client grant.

scope

Contains all the allowed scopes for the client.

Getting a client grants

We can use the client-grants endpoint to retrieve information about the client grants issued to different clients and apply filtering to the results. This can be useful in various scenarios where we need to review the client grants and their parameters.

Using the client-grants endpoint, we can retrieve a list of all the client grants issued to a specific client. Additionally, we can filter the results, such as filtering by client or audience, to narrow down the list of client grants.

Request parameters

This API call does not take body parameters but supports some query parameters to filter the response. Let's see these parameters in the table below:

Parameter Name

Type

Category

Description

id

String

Optional

Defines the unique identification of the client grant.

client_id

String

Optional

Defines the unique identification of the client.

audience

String

Optional

Defines the API Identifier as a client-grant audience.

per_page

Integer

Optional

Defines the number of results per page.

page

Integer

Optional

Defines the page number to return.

The following code will list all the client grants. Click the “Run” button to execute the code.

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

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

  • Line 4: We define the endpoint URL to retrieve the client grants.

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

  • Line 25: We invoke the getAllClientsGrants function.

Response fields

The successful execution of the above code will list all the created client grants and returns the following details.

Name

Description

id

Contains the client grant ID.

client_id

Contains the unique identifier of the client.

audience

Contains the API identifier for the client grant.

scope

Contains all the allowed scopes for the client.