Creating a Client and Getting All Clients

A client is an important component of the authentication process. A client makes a lot of things easier and encapsulates many low-level things at the same time. In this lesson, we'll see how we can create a client or an application and get a list of our clients using an API call.

We'll use the https://{{DOMAIN}}/api/v2/clients endpoint to achieve these tasks. Creating a client is a POST request, while getting all clients is a GET request.

Press + to interact

Creating a client in Auth0 is crucial in establishing secure authentication and authorization for our application. In Auth0, a client represents an application or service that uses Auth0 for authentication and authorization. To create a client, we must provide an access token that has been granted the create:clients scope. This access token allows us to create and configure a client, enabling our application or service to authenticate and authorize users through Auth0 securely. The endpoint requires our access token to have create:clients scope.

Parameter Name	Type	Category	Description
`name`	String	Required	Defines the name of the application. The length of this string should be at least one character. The `<` or `>` signs are not allowed
`description`	String	Optional	Defines the client's description with a maximum limit of 140 characters.
`callbacks`	String	Optional	Takes a list of valid URLs that this application will use to redirect the user after logging in. In the case of multiple URLs, they are separated by a comma.
`grant_types`	String	Optional	Defines a comma-separated list of supported grant types we want for this client. The following are some values that can be used: `authorization_code`, `implicit`, `refresh_token`, `client_credentials`, and `password`.
`app_type`	String	Optional	Defines the type of application. Auth0 supports majorly four types of applications, as mentioned below: `spa`, `native`, `non_interactive`, and `regular_web`.
`allowed_logout_urls`	String	Optional	Defines valid URLs in the form of a comma-separated list to redirect the users after they log out.
`refresh_token.rotation_type`	String	Required	Defines the rotation type of the refresh token if it is rotating or non-rotating. The `refresh_token` object is optional, but if it is defined, then `rotation_type` is required.
`refresh_token.expiration_type`	String	Required	Defines the expiration type of the refresh token. Its value can either be `expiring` or `non-expiring`. It is required if the `refresh_token` object is defined.
`refresh_token.token_lifetime`	Integer	Optional	Defines the time in seconds for which this refresh token remains valid.

Press + to interact

// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/clients');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const bodyParameters = JSON.stringify({
  "name": "Sample Client",
  "description": "A sample client created by an API call",
  "callbacks": [
    "https://ed-6532034605875200.educative.run/callback"
  ],
  "grant_types": [
    "client_credentials"
  ],
  "app_type": "non_interactive",
});
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
async function createClient() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
createClient();

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

Line 4: We define the endpoint to create a client.
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–21: We define the bodyParameters object.
- Line 12: We define the name of our client.
- Line 13: We define the description of our client.
- Lines 14–16: We define the callback URL in callbacks.
- Lines 17–19: We define grant types for our clients.
- Line 20: We define our application type as non_interactive, which means we are creating a machine-to-machine application that runs on the backend.
Lines 23–27: We define the options object used to pass data required to make an API call.
Line 31: We make a POST request using the fetch function.
Line 38: We invoke the createClient function.

Response fields

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

Getting all clients

Sometimes, we may need to retrieve all the available clients—this endpoint is useful in situations like these. In this section, we'll see how we can retrieve all the clients and which parameters can be used to filter the results. This operation requires our access token to have read:clients, read:client_keys scopes. Some fields can only be retrieved if the appropriate scope is granted, like encryption_key, encryption_key.pub, and client_secret, which are accessible via the read:client_keys scope.

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
`fields`	String	Optional	Defines the fields we want to include or exclude in the response. It takes a comma-separated list of fields.
`include_fields`	Boolean	Optional	Defines the inclusion and exclusion of the fields defined in the `fields` parameter. If the value is `true`, the mentioned fields are to be included in the response, otherwise excluded.
`page`	Integer	Optional	Defines the page index from the result to be returned. The first page has an index of 0.
`per_page`	Integer	Optional	Defines the number of items on a single page. Its default value is 50, and the maximum value is 100.
`include_totals`	Boolean	Optional	Returns the total count of users along with the result in an object. Its default value is `false`.
`is_global`	Boolean	Optional	Applies a filter on the `global` field.
`is_first_party`	Boolean	Optional	Filters the clients based on their first-party and third-party status. A first-party client is a client owned and operated by the same organization as the Auth0 account.
`app_type`	String	Optional	Filters the client based on the mentioned application type.

Press + to interact

// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/clients');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
// Define Query Parameters here
const queryParameters = new URLSearchParams({
  include_totals: true,
  is_global: false,
});
const options = {
  method: 'GET',
  headers: headerParameters,
};
async function getAllClients() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getAllClients();

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

Line 4: We define endpointUrl for this API call.
Lines 12–15: We define two query parameters that apply the filter on the response.
Line 24: We assign the query parameters defined in queryParameter to endpointUrl.
Line 25: We make a GET request using the fetch function.
Line 32: We invoke the getAllClients function.

Response fields

The successful execution of the above code returns all clients in a clients array along with some additional fields. Let's see them in the table below:

Name	Description
`tenant`	Gives the tenant name of this client.
`client_id`	Defines the unique identification of the client.
`client_secret`	Defines the client's secret. This must be kept very carefully and should not be shared publically. It is recommended not to define `client_secret` in the request's body and let the API generate a safe secret.
`refresh_token`	Defines the attributes related to the refresh token. We have seen some of them in the request parameters table.

Response Field	Description
`total`	Shows the total count of clients.
`start`	Shows the starting page index of the response.
`limit`	Shows the limit of items that can be displayed per page.
`clients`	The array that contains all clients and the corresponding information. The fields of the array have been described earlier.

Introduction

Clients

Connections

Users and Roles

Attack Protection

Authentication

Auth0 API Integration in React

Conclusion