Creating and Getting All Connections

Learn to create connections and get all connections using Auth0 API.

We'll cover the following

A connection is an important component of the authentication process that allows users to authenticate with a specific identity provider. It is used to configure and manage the connection to an external identity provider such as Google, Facebook, or a database of users.

In this lesson, we'll see how we can create a connection for an application and get a list of our connections using an API call. We'll use the https://{{DOMAIN}}/api/v2/connections endpoint to achieve these tasks. Creating a connection is a POST request, while getting all connections is a GET request.

Press + to interact
Creating a connection and getting all connections endpoints
Creating a connection and getting all connections endpoints

Creating a connection

Creating a connection is essential in configuring the Auth0 tenant to handle user authentication for our application. In this lesson, we’ll explore the steps required to create a connection in Auth0, including the different types of connections available, and how to configure them to suit specific authentication needs.

Request parameters

In this API call, we will use a POST request. Therefore, we have a list of parameters that can be passed as body parameters. This endpoint takes an extensive list of parameters. Let's look at some important ones in the table below:

Parameter Name

Type

Category

Description

name

String

Required

Defines the name of the connection. The length of this string must not exceed 128 characters. The string should start and end with alphabets.

strategy

String

Required

Defines the identifier for a connection.

display_name

String

Optional

Defines the display name of the connection.

enabled_clients

Array

Optional

Defines the client IDs, which are enabled by the connection.

realms

Array

Optional

Defines the realms which can use this connection.

password_complexity_options

String

Optional

Defines the password complexity options.

The following code creates a connection and returns its connection ID and name.  Don't forget to click the “Save” button to use that ID in the upcoming lessons. Click the “Run” button to create a connection in the code widget below:

Press + to interact
// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/connections');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const bodyParameters = JSON.stringify({
    name: `Sample-Connection-${Math.floor(Math.random()*99999)}`,
    strategy: 'auth0',
    enabled_clients: [
      '{{CLIENT_ID}}'
      ],
  });
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
async function createConnection() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
createConnection();

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

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

  • 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–17: We define the bodyParameters object.

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

    • Line 13: We define a strategy parameter and set it to auth0 .

    • Lines 14–16: We define an enabled_clients parameter and set it to the client ID of the client that we want to access this connection.

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

Note: To use the created connection in the upcoming lessons. Please visit the Database page, select the created connection, and enable the “Requires Username” settings from the connection settings.

Response fields

The successful execution of the above code creates a new connection and returns its details. Some important response fields are as follows:

Name

Description

name

Contains the connection name created.

display_name

Contains the connection display name.

id

Contains the ID of the connection.

strategy

Contains the identifier for the connection.

realms

Contains the realms for the connection.

enabled_clients

Contains the enabled clients for the connection.

Getting all connections

This endpoint allows us to retrieve all available connections when needed. It requires an access token with read:connections scope. To utilize this endpoint, we need to send a GET HTTP request to the connections endpoint.

Request parameters

Next, let's learn how we can use this endpoint. To retrieve all the connections, we’ll need to send a GET HTTP request to the specified endpoint. We can filter the results by using specific parameters. Some of the important parameters are as follows:

Parameter Name

Type

Category

Description

per_page

Integer

Optional

Defines the number of results per page that will be reflected in the response.

fields

String

Optional

Filters the fields that will be included in the response.

include_fields

Boolean

Optional

Used to confirm whether the filtered value should be included in the response or not.

include_totals

Boolean

Optional

Used to confirm whether the filtered summary should be included in the response or not.

The following code retrievesall the connections that we have. Click the “Run” button to retrieve all connections in the code widget below:

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

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

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

  • Lines 12–15: We define query parameters that apply the filter on the response.

    • Line 13: We define the number of results per page that will be reflected in the response.

    • Line 14: We set the value of the include_totals parameter to true.

  • Line 24: We define the query parameters that filter the response fields.

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

  • Line 32: We invoke the getAllConnection function.

Response fields

The successful execution of the above code will list all the connections and return metadata that the important response field follows.

Name

Description

name

Contains the connection name listed.

display_name

Contains the connection display name.

id

Contains the ID of the connection.

strategy

Contains the identifier for the connection.

realms

Contains the realms for the connection.

enabled_clients

Contains the enabled clients for the connection.